This is ../../info/org, produced by makeinfo version 4.13 from org.texi.

This manual is for Org version 7.8.11.

   Copyright (C) 2004-2012  Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, with the Front-Cover texts
     being "A GNU Manual," and with the Back-Cover Texts as in (a)
     below.  A copy of the license is included in the section entitled
     "GNU Free Documentation License."

     (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
     modify this GNU manual.  Buying copies from the FSF supports it in
     developing GNU and promoting software freedom."

     This document is part of a collection distributed under the GNU
     Free Documentation License.  If you want to distribute this
     document separately from the collection, you can do so by adding a
     copy of the license to the document, as described in section 6 of
     the license.

INFO-DIR-SECTION Emacs editing modes
START-INFO-DIR-ENTRY
* Org Mode: (org).      Outline-based notes management and organizer
END-INFO-DIR-ENTRY


File: org,  Node: Matching tags and properties,  Next: Timeline,  Prev: Global TODO list,  Up: Built-in agenda views

10.3.3 Matching tags and properties
-----------------------------------

If headlines in the agenda files are marked with _tags_ (*note Tags::),
or have properties (*note Properties and Columns::), you can select
headlines based on this metadata and collect them into an agenda
buffer.  The match syntax described here also applies when creating
sparse trees with `C-c / m'.

`C-c a m     (`org-tags-view')'
     Produce a list of all headlines that match a given set of tags.
     The command prompts for a selection criterion, which is a boolean
     logic expression with tags, like `+work+urgent-withboss' or
     `work|home' (*note Tags::).  If you often need a specific search,
     define a custom command for it (*note Agenda dispatcher::).  

`C-c a M     (`org-tags-view')'
     Like `C-c a m', but only select headlines that are also TODO items
     in a not-DONE state and force checking subitems (see variable
     `org-tags-match-list-sublevels').  To exclude scheduled/deadline
     items, see the variable
     `org-agenda-tags-todo-honor-ignore-options'.  Matching specific
     TODO keywords together with a tags match is also possible, see
     *note Tag searches::.

   The commands available in the tags list are described in *note
Agenda commands::.

Match syntax
............

A search string can use Boolean operators `&' for AND and `|' for OR.
`&' binds more strongly than `|'.  Parentheses are currently not
implemented.  Each element in the search is either a tag, a regular
expression matching tags, or an expression like `PROPERTY OPERATOR
VALUE' with a comparison operator, accessing a property value.  Each
element may be preceded by `-', to select against it, and `+' is
syntactic sugar for positive selection.  The AND operator `&' is
optional when `+' or `-' is present.  Here are some examples, using
only tags.

`+work-boss'
     Select headlines tagged `:work:', but discard those also tagged
     `:boss:'.

`work|laptop'
     Selects lines tagged `:work:' or `:laptop:'.

`work|laptop+night'
     Like before, but require the `:laptop:' lines to be tagged also
     `:night:'.

   Instead of a tag, you may also specify a regular expression enclosed
in curly braces.  For example, `work+{^boss.*}' matches headlines that
contain the tag `:work:' and any tag starting with `boss'.

   You may also test for properties (*note Properties and Columns::) at
the same time as matching tags.  The properties may be real properties,
or special properties that represent other metadata (*note Special
properties::).  For example, the "property" `TODO' represents the TODO
keyword of the entry.  Or, the "property" `LEVEL' represents the level
of an entry.  So a search `+LEVEL=3+boss-TODO="DONE"' lists all level
three headlines that have the tag `boss' and are _not_ marked with the
TODO keyword DONE.  In buffers with `org-odd-levels-only' set, `LEVEL'
does not count the number of stars, but `LEVEL=2' will correspond to 3
stars etc.

   Here are more examples:
`work+TODO="WAITING"'
     Select `:work:'-tagged TODO lines with the specific TODO keyword
     `WAITING'.

`work+TODO="WAITING"|home+TODO="WAITING"'
     Waiting tasks both at work and at home.

   When matching properties, a number of different operators can be
used to test the value of a property.  Here is a complex example:

     +work-boss+PRIORITY="A"+Coffee="unlimited"+Effort<2         \
              +With={Sarah\|Denny}+SCHEDULED>="<2008-10-11>"

The type of comparison will depend on how the comparison value is
written:
   - If the comparison value is a plain number, a numerical comparison
     is done, and the allowed operators are `<', `=', `>', `<=', `>=',
     and `<>'.

   - If the comparison value is enclosed in double-quotes, a string
     comparison is done, and the same operators are allowed.

   - If the comparison value is enclosed in double-quotes _and_ angular
     brackets (like `DEADLINE<="<2008-12-24 18:30>"'), both values are
     assumed to be date/time specifications in the standard Org way,
     and the comparison will be done accordingly.  Special values that
     will be recognized are `"<now>"' for now (including time), and
     `"<today>"', and `"<tomorrow>"' for these days at 0:00 hours, i.e.
     without a time specification.  Also strings like `"<+5d>"' or
     `"<-2m>"' with units `d', `w', `m', and `y' for day, week, month,
     and year, respectively, can be used.

   - If the comparison value is enclosed in curly braces, a regexp
     match is performed, with `=' meaning that the regexp matches the
     property value, and `<>' meaning that it does not match.

   So the search string in the example finds entries tagged `:work:' but
not `:boss:', which also have a priority value `A', a `:Coffee:'
property with the value `unlimited', an `Effort' property that is
numerically smaller than 2, a `:With:' property that is matched by the
regular expression `Sarah\|Denny', and that are scheduled on or after
October 11, 2008.

   Accessing TODO, LEVEL, and CATEGORY during a search is fast.
Accessing any other properties will slow down the search.  However,
once you have paid the price by accessing one property, testing
additional properties is cheap again.

   You can configure Org mode to use property inheritance during a
search, but beware that this can slow down searches considerably.  See
*note Property inheritance::, for details.

   For backward compatibility, and also for typing speed, there is also
a different way to test TODO states in a search.  For this, terminate
the tags/property part of the search string (which may include several
terms connected with `|') with a `/' and then specify a Boolean
expression just for TODO keywords.  The syntax is then similar to that
for tags, but should be applied with care: for example, a positive
selection on several TODO keywords cannot meaningfully be combined with
boolean AND.  However, _negative selection_ combined with AND can be
meaningful.  To make sure that only lines are checked that actually
have any TODO keyword (resulting in a speed-up), use `C-c a M', or
equivalently start the TODO part after the slash with `!'.  Using `C-c
a M' or `/!' will not match TODO keywords in a DONE state.  Examples:

`work/WAITING'
     Same as `work+TODO="WAITING"'

`work/!-WAITING-NEXT'
     Select `:work:'-tagged TODO lines that are neither `WAITING' nor
     `NEXT'

`work/!+WAITING|+NEXT'
     Select `:work:'-tagged TODO lines that are either `WAITING' or
     `NEXT'.


File: org,  Node: Timeline,  Next: Search view,  Prev: Matching tags and properties,  Up: Built-in agenda views

10.3.4 Timeline for a single file
---------------------------------

The timeline summarizes all time-stamped items from a single Org mode
file in a _time-sorted view_.  The main purpose of this command is to
give an overview over events in a project.

`C-c a L     (`org-timeline')'
     Show a time-sorted view of the Org file, with all time-stamped
     items.  When called with a `C-u' prefix, all unfinished TODO
     entries (scheduled or not) are also listed under the current date.

The commands available in the timeline buffer are listed in *note
Agenda commands::.


File: org,  Node: Search view,  Next: Stuck projects,  Prev: Timeline,  Up: Built-in agenda views

10.3.5 Search view
------------------

This agenda view is a general text search facility for Org mode entries.
It is particularly useful to find notes.

`C-c a s     (`org-search-view')'
     This is a special search that lets you select entries by matching
     a substring or specific words using a boolean logic.
   For example, the search string `computer equipment' will find entries
that contain `computer equipment' as a substring.  If the two words are
separated by more space or a line break, the search will still match.
Search view can also search for specific keywords in the entry, using
Boolean logic.  The search string `+computer +wifi -ethernet
-{8\.11[bg]}' will search for note entries that contain the keywords
`computer' and `wifi', but not the keyword `ethernet', and which are
also not matched by the regular expression `8\.11[bg]', meaning to
exclude both 8.11b and 8.11g.  The first `+' is necessary to turn on
word search, other `+' characters are optional.  For more details, see
the docstring of the command `org-search-view'.

   Note that in addition to the agenda files, this command will also
search the files listed in `org-agenda-text-search-extra-files'.


File: org,  Node: Stuck projects,  Prev: Search view,  Up: Built-in agenda views

10.3.6 Stuck projects
---------------------

If you are following a system like David Allen's GTD to organize your
work, one of the "duties" you have is a regular review to make sure
that all projects move along.  A _stuck_ project is a project that has
no defined next actions, so it will never show up in the TODO lists Org
mode produces.  During the review, you need to identify such projects
and define next actions for them.

`C-c a #     (`org-agenda-list-stuck-projects')'
     List projects that are stuck.  

`C-c a !'
     Customize the variable `org-stuck-projects' to define what a stuck
     project is and how to find it.

   You almost certainly will have to configure this view before it will
work for you.  The built-in default assumes that all your projects are
level-2 headlines, and that a project is not stuck if it has at least
one entry marked with a TODO keyword TODO or NEXT or NEXTACTION.

   Let's assume that you, in your own way of using Org mode, identify
projects with a tag PROJECT, and that you use a TODO keyword MAYBE to
indicate a project that should not be considered yet.  Let's further
assume that the TODO keyword DONE marks finished projects, and that NEXT
and TODO indicate next actions.  The tag @SHOP indicates shopping and
is a next action even without the NEXT tag.  Finally, if the project
contains the special word IGNORE anywhere, it should not be listed
either.  In this case you would start by identifying eligible projects
with a tags/todo match(1) `+PROJECT/-MAYBE-DONE', and then check for
TODO, NEXT, @SHOP, and IGNORE in the subtree to identify projects that
are not stuck.  The correct customization for this is

     (setq org-stuck-projects
           '("+PROJECT/-MAYBE-DONE" ("NEXT" "TODO") ("@SHOP")
                                    "\\<IGNORE\\>"))

   Note that if a project is identified as non-stuck, the subtree of
this entry will still be searched for stuck projects.

   ---------- Footnotes ----------

   (1) *Note Tag searches::.


File: org,  Node: Presentation and sorting,  Next: Agenda commands,  Prev: Built-in agenda views,  Up: Agenda Views

10.4 Presentation and sorting
=============================

Before displaying items in an agenda view, Org mode visually prepares
the items and sorts them.  Each item occupies a single line.  The line
starts with a _prefix_ that contains the _category_ (*note Categories::)
of the item and other important information.  You can customize in which
column tags will be displayed through `org-agenda-tags-column'.  You can
also customize the prefix using the option `org-agenda-prefix-format'.
This prefix is followed by a cleaned-up version of the outline headline
associated with the item.

* Menu:

* Categories::                  Not all tasks are equal
* Time-of-day specifications::  How the agenda knows the time
* Sorting of agenda items::     The order of things


File: org,  Node: Categories,  Next: Time-of-day specifications,  Prev: Presentation and sorting,  Up: Presentation and sorting

10.4.1 Categories
-----------------

The category is a broad label assigned to each agenda item.  By default,
the category is simply derived from the file name, but you can also
specify it with a special line in the buffer, like this(1):

     #+CATEGORY: Thesis

If you would like to have a special CATEGORY for a single entry or a
(sub)tree, give the entry a `:CATEGORY:' property with the special
category you want to apply as the value.

The display in the agenda buffer looks best if the category is not
longer than 10 characters.

You can set up icons for category by customizing the
`org-agenda-category-icon-alist' variable.

   ---------- Footnotes ----------

   (1) For backward compatibility, the following also works: if there
are several such lines in a file, each specifies the category for the
text below it.  The first category also applies to any text before the
first CATEGORY line.  However, using this method is _strongly_
deprecated as it is incompatible with the outline structure of the
document.  The correct method for setting multiple categories in a
buffer is using a property.


File: org,  Node: Time-of-day specifications,  Next: Sorting of agenda items,  Prev: Categories,  Up: Presentation and sorting

10.4.2 Time-of-day specifications
---------------------------------

Org mode checks each agenda item for a time-of-day specification.  The
time can be part of the timestamp that triggered inclusion into the
agenda, for example as in `<2005-05-10 Tue 19:00>'.  Time ranges can be
specified with two timestamps, like
`<2005-05-10 Tue 20:30>--<2005-05-10 Tue 22:15>'.

   In the headline of the entry itself, a time(range) may also appear as
plain text (like `12:45' or a `8:30-1pm').  If the agenda integrates
the Emacs diary (*note Weekly/daily agenda::), time specifications in
diary entries are recognized as well.

   For agenda display, Org mode extracts the time and displays it in a
standard 24 hour format as part of the prefix.  The example times in
the previous paragraphs would end up in the agenda like this:

         8:30-13:00 Arthur Dent lies in front of the bulldozer
        12:45...... Ford Prefect arrives and takes Arthur to the pub
        19:00...... The Vogon reads his poem
        20:30-22:15 Marvin escorts the Hitchhikers to the bridge

   If the agenda is in single-day mode, or for the display of today, the
timed entries are embedded in a time grid, like

         8:00...... ------------------
         8:30-13:00 Arthur Dent lies in front of the bulldozer
        10:00...... ------------------
        12:00...... ------------------
        12:45...... Ford Prefect arrives and takes Arthur to the pub
        14:00...... ------------------
        16:00...... ------------------
        18:00...... ------------------
        19:00...... The Vogon reads his poem
        20:00...... ------------------
        20:30-22:15 Marvin escorts the Hitchhikers to the bridge

   The time grid can be turned on and off with the variable
`org-agenda-use-time-grid', and can be configured with
`org-agenda-time-grid'.


File: org,  Node: Sorting of agenda items,  Prev: Time-of-day specifications,  Up: Presentation and sorting

10.4.3 Sorting of agenda items
------------------------------

Before being inserted into a view, the items are sorted.  How this is
done depends on the type of view.
   * For the daily/weekly agenda, the items for each day are sorted.
     The default order is to first collect all items containing an
     explicit time-of-day specification.  These entries will be shown
     at the beginning of the list, as a _schedule_ for the day.  After
     that, items remain grouped in categories, in the sequence given by
     `org-agenda-files'.  Within each category, items are sorted by
     priority (*note Priorities::), which is composed of the base
     priority (2000 for priority `A', 1000 for `B', and 0 for `C'),
     plus additional increments for overdue scheduled or deadline items.

   * For the TODO list, items remain in the order of categories, but
     within each category, sorting takes place according to priority
     (*note Priorities::).  The priority used for sorting derives from
     the priority cookie, with additions depending on how close an item
     is to its due or scheduled date.

   * For tags matches, items are not sorted at all, but just appear in
     the sequence in which they are found in the agenda files.

   Sorting can be customized using the variable
`org-agenda-sorting-strategy', and may also include criteria based on
the estimated effort of an entry (*note Effort estimates::).


File: org,  Node: Agenda commands,  Next: Custom agenda views,  Prev: Presentation and sorting,  Up: Agenda Views

10.5 Commands in the agenda buffer
==================================

Entries in the agenda buffer are linked back to the Org file or diary
file where they originate.  You are not allowed to edit the agenda
buffer itself, but commands are provided to show and jump to the
original entry location, and to edit the Org files "remotely" from the
agenda buffer.  In this way, all information is stored only once,
removing the risk that your agenda and note files may diverge.

   Some commands can be executed with mouse clicks on agenda lines.  For
the other commands, the cursor needs to be in the desired line.

Motion
......

`n     (`org-agenda-next-line')'
     Next line (same as <down> and `C-n').  

`p     (`org-agenda-previous-line')'
     Previous line (same as <up> and `C-p').

View/Go to Org file
...................

`<SPC>  or  mouse-3     (`org-agenda-show-and-scroll-up')'
     Display the original location of the item in another window.  With
     prefix arg, make sure that the entire entry is made visible in the
     outline, not only the heading.  

`L     (`org-agenda-recenter')'
     Display original location and recenter that window.  

`<TAB>  or  mouse-2     (`org-agenda-goto')'
     Go to the original location of the item in another window.  

`<RET>     (`org-agenda-switch-to')'
     Go to the original location of the item and delete other windows.  

`F     (`org-agenda-follow-mode')'
     Toggle Follow mode.  In Follow mode, as you move the cursor through
     the agenda buffer, the other window always shows the corresponding
     location in the Org file.  The initial setting for this mode in new
     agenda buffers can be set with the variable
     `org-agenda-start-with-follow-mode'.  

`C-c C-x b     (`org-agenda-tree-to-indirect-buffer')'
     Display the entire subtree of the current item in an indirect
     buffer.  With a numeric prefix argument N, go up to level N and
     then take that tree.  If N is negative, go up that many levels.
     With a `C-u' prefix, do not remove the previously used indirect
     buffer.

`C-c C-o     (`org-agenda-open-link')'
     Follow a link in the entry.  This will offer a selection of any
     links in the text belonging to the referenced Org node.  If there
     is only one link, it will be followed without a selection prompt.

Change display
..............

`A'
     Interactively select another agenda view and append it to the
     current view.  

`o'
     Delete other windows.  

`v d  or short  d     (`org-agenda-day-view')'
`v w  or short  w     (`org-agenda-week-view')'
`v m     (`org-agenda-month-view')'
`v y     (`org-agenda-year-view')'
`v SPC     (`org-agenda-reset-view')'
     Switch to day/week/month/year view.  When switching to day or week
     view, this setting becomes the default for subsequent agenda
     refreshes.  Since month and year views are slow to create, they do
     not become the default.  A numeric prefix argument may be used to
     jump directly to a specific day of the year, ISO week, month, or
     year, respectively.  For example, `32 d' jumps to February 1st, `9
     w' to ISO week number 9.  When setting day, week, or month view, a
     year may be encoded in the prefix argument as well.  For example,
     `200712 w' will jump to week 12 in 2007.  If such a year
     specification has only one or two digits, it will be mapped to the
     interval 1938-2037.  `v <SPC>' will reset to what is set in
     `org-agenda-span'.  

`f     (`org-agenda-later')'
     Go forward in time to display the following
     `org-agenda-current-span' days.  For example, if the display
     covers a week, switch to the following week.  With prefix arg, go
     forward that many times `org-agenda-current-span' days.  

`b     (`org-agenda-earlier')'
     Go backward in time to display earlier dates.  

`.     (`org-agenda-goto-today')'
     Go to today.  

`j     (`org-agenda-goto-date')'
     Prompt for a date and go there.  

`J     (`org-agenda-clock-goto')'
     Go to the currently clocked-in task in the agenda buffer.  

`D     (`org-agenda-toggle-diary')'
     Toggle the inclusion of diary entries.  See *note Weekly/daily
     agenda::.  

`v l  or short  l     (`org-agenda-log-mode')'
     Toggle Logbook mode.  In Logbook mode, entries that were marked
     DONE while logging was on (variable `org-log-done') are shown in
     the agenda, as are entries that have been clocked on that day.
     You can configure the entry types that should be included in log
     mode using the variable `org-agenda-log-mode-items'.  When called
     with a `C-u' prefix, show all possible logbook entries, including
     state changes.  When called with two prefix args `C-u C-u', show
     only logging information, nothing else.  `v L' is equivalent to
     `C-u v l'.  

`v [  or short  [     (`org-agenda-manipulate-query-add')'
     Include inactive timestamps into the current view.  Only for
     weekly/daily agenda and timeline views.  

`v a     (`org-agenda-archives-mode')'
`v A     (`org-agenda-archives-mode 'files')'
     Toggle Archives mode.  In Archives mode, trees that are marked
     `ARCHIVED' are also scanned when producing the agenda.  When you
     use the capital `A', even all archive files are included.  To exit
     archives mode, press `v a' again.  

`v R  or short  R     (`org-agenda-clockreport-mode')'
     Toggle Clockreport mode.  In Clockreport mode, the daily/weekly
     agenda will always show a table with the clocked times for the
     timespan and file scope covered by the current agenda view.  The
     initial setting for this mode in new agenda buffers can be set
     with the variable `org-agenda-start-with-clockreport-mode'.  By
     using a prefix argument when toggling this mode (i.e. `C-u R'),
     the clock table will not show contributions from entries that are
     hidden by agenda filtering(1).  See also the variable
     `org-clock-report-include-clocking-task'.  

`v c'
     Show overlapping clock entries, clocking gaps, and other clocking
     problems in the current agenda range.  You can then visit clocking
     lines and fix them manually.  See the variable
     `org-agenda-clock-consistency-checks' for information on how to
     customize the definition of what constituted a clocking problem.
     To return to normal agenda display, press `l' to exit Logbook mode.  

`v E  or short  E     (`org-agenda-entry-text-mode')'
     Toggle entry text mode.  In entry text mode, a number of lines
     from the Org outline node referenced by an agenda line will be
     displayed below the line.  The maximum number of lines is given by
     the variable `org-agenda-entry-text-maxlines'.  Calling this
     command with a numeric prefix argument will temporarily modify
     that number to the prefix value.  

`G     (`org-agenda-toggle-time-grid')'
     Toggle the time grid on and off.  See also the variables
     `org-agenda-use-time-grid' and `org-agenda-time-grid'.  

`r     (`org-agenda-redo')'
     Recreate the agenda buffer, for example to reflect the changes
     after modification of the timestamps of items with `S-<left>' and
     `S-<right>'.  When the buffer is the global TODO list, a prefix
     argument is interpreted to create a selective list for a specific
     TODO keyword.  

`g     (`org-agenda-redo')'
     Same as `r'.  

`C-x C-s  or short  s     (`org-save-all-org-buffers')'
     Save all Org buffers in the current Emacs session, and also the
     locations of IDs.  

`C-c C-x C-c     (`org-agenda-columns')'
     Invoke column view (*note Column view::) in the agenda buffer.
     The column view format is taken from the entry at point, or (if
     there is no entry at point), from the first entry in the agenda
     view.  So whatever the format for that entry would be in the
     original buffer (taken from a property, from a `#+COLUMNS' line,
     or from the default variable `org-columns-default-format'), will
     be used in the agenda.

`C-c C-x >     (`org-agenda-remove-restriction-lock')'
     Remove the restriction lock on the agenda, if it is currently
     restricted to a file or subtree (*note Agenda files::).

Secondary filtering and query editing
.....................................

`<     (`org-agenda-filter-by-category')'
     Filter the current agenda view with respect to the category of the
     item at point.  Pressing `<' another time will remove this filter.
     You can add a filter preset through the option
     `org-agenda-category-filter-preset' (see below.)

`/     (`org-agenda-filter-by-tag')'
     Filter the current agenda view with respect to a tag and/or effort
     estimates.  The difference between this and a custom agenda
     command is that filtering is very fast, so that you can switch
     quickly between different filters without having to recreate the
     agenda.(2)

     You will be prompted for a tag selection letter; <SPC> will mean
     any tag at all.  Pressing <TAB> at that prompt will offer use
     completion to select a tag (including any tags that do not have a
     selection character).  The command then hides all entries that do
     not contain or inherit this tag.  When called with prefix arg,
     remove the entries that _do_ have the tag.  A second `/' at the
     prompt will turn off the filter and unhide any hidden entries.  If
     the first key you press is either `+' or `-', the previous filter
     will be narrowed by requiring or forbidding the selected
     additional tag.  Instead of pressing `+' or `-' after `/', you can
     also immediately use the `\' command.

     In order to filter for effort estimates, you should set up allowed
     efforts globally, for example
          (setq org-global-properties
              '(("Effort_ALL". "0 0:10 0:30 1:00 2:00 3:00 4:00")))
     You can then filter for an effort by first typing an operator, one
     of `<', `>', and `=', and then the one-digit index of an effort
     estimate in your array of allowed values, where `0' means the 10th
     value.  The filter will then restrict to entries with effort
     smaller-or-equal, equal, or larger-or-equal than the selected
     value.  If the digits 0-9 are not used as fast access keys to
     tags, you can also simply press the index digit directly without
     an operator.  In this case, `<' will be assumed.  For application
     of the operator, entries without a defined effort will be treated
     according to the value of `org-sort-agenda-noeffort-is-high'.  To
     filter for tasks without effort definition, press `?' as the
     operator.

     Org also supports automatic, context-aware tag filtering.  If the
     variable `org-agenda-auto-exclude-function' is set to a
     user-defined function, that function can decide which tags should
     be excluded from the agenda automatically.  Once this is set, the
     `/' command then accepts `RET' as a sub-option key and runs the
     auto exclusion logic.  For example, let's say you use a `Net' tag
     to identify tasks which need network access, an `Errand' tag for
     errands in town, and a `Call' tag for making phone calls.  You
     could auto-exclude these tags based on the availability of the
     Internet, and outside of business hours, with something like this:

          (defun org-my-auto-exclude-function (tag)
            (and (cond
                  ((string= tag "Net")
                   (/= 0 (call-process "/sbin/ping" nil nil nil
                                       "-c1" "-q" "-t1" "mail.gnu.org")))
                  ((or (string= tag "Errand") (string= tag "Call"))
                   (let ((hour (nth 2 (decode-time))))
                     (or (< hour 8) (> hour 21)))))
                 (concat "-" tag)))

          (setq org-agenda-auto-exclude-function 'org-my-auto-exclude-function)

`\     (`org-agenda-filter-by-tag-refine')'
     Narrow the current agenda filter by an additional condition.  When
     called with prefix arg, remove the entries that _do_ have the tag,
     or that do match the effort criterion.  You can achieve the same
     effect by pressing `+' or `-' as the first key after the `/'
     command.

`[ ] { }'

    in search view
          add new search words (`[' and `]') or new regular expressions
          (`{' and `}') to the query string.  The opening bracket/brace
          will add a positive search term prefixed by `+', indicating
          that this search term must occur/match in the entry.  The
          closing bracket/brace will add a negative search term which
          must not occur/match in the entry for it to be selected.

Remote editing
..............

`0-9'
     Digit argument.  

`C-_     (`org-agenda-undo')'
     Undo a change due to a remote editing command.  The change is
     undone both in the agenda buffer and in the remote buffer.  

`t     (`org-agenda-todo')'
     Change the TODO state of the item, both in the agenda and in the
     original org file.  

`C-S-<right>     (`org-agenda-todo-nextset')'

`C-S-<left>     (`org-agenda-todo-previousset')'
     Switch to the next/previous set of TODO keywords.  

`C-k     (`org-agenda-kill')'
     Delete the current agenda item along with the entire subtree
     belonging to it in the original Org file.  If the text to be
     deleted remotely is longer than one line, the kill needs to be
     confirmed by the user.  See variable `org-agenda-confirm-kill'.  

`C-c C-w     (`org-agenda-refile')'
     Refile the entry at point.  

`C-c C-x C-a  or short  a     (`org-agenda-archive-default-with-confirmation')'
     Archive the subtree corresponding to the entry at point using the
     default archiving command set in `org-archive-default-command'.
     When using the `a' key, confirmation will be required.  

`C-c C-x a     (`org-agenda-toggle-archive-tag')'
     Toggle the ARCHIVE tag for the current headline.  

`C-c C-x A     (`org-agenda-archive-to-archive-sibling')'
     Move the subtree corresponding to the current entry to its _archive
     sibling_.  

`C-c C-x C-s  or short  $     (`org-agenda-archive')'
     Archive the subtree corresponding to the current headline.  This
     means the entry will be moved to the configured archive location,
     most likely a different file.  

`T     (`org-agenda-show-tags')'
     Show all tags associated with the current item.  This is useful if
     you have turned off `org-agenda-show-inherited-tags', but still
     want to see all tags of a headline occasionally.  

`:     (`org-agenda-set-tags')'
     Set tags for the current headline.  If there is an active region
     in the agenda, change a tag for all headings in the region.  

`,'
     Set the priority for the current item (`org-agenda-priority').
     Org mode prompts for the priority character.  If you reply with
     <SPC>, the priority cookie is removed from the entry.  

`P     (`org-agenda-show-priority')'
     Display weighted priority of current item.  

`+  or  S-<up>     (`org-agenda-priority-up')'
     Increase the priority of the current item.  The priority is
     changed in the original buffer, but the agenda is not resorted.
     Use the `r' key for this.  

`-  or  S-<down>     (`org-agenda-priority-down')'
     Decrease the priority of the current item.  

`z  or  C-c C-z     (`org-agenda-add-note')'
     Add a note to the entry.  This note will be recorded, and then
     filed to the same location where state change notes are put.
     Depending on `org-log-into-drawer', this may be inside a drawer.  

`C-c C-a     (`org-attach')'
     Dispatcher for all command related to attachments.  

`C-c C-s     (`org-agenda-schedule')'
     Schedule this item.  With prefix arg remove the scheduling
     timestamp 

`C-c C-d     (`org-agenda-deadline')'
     Set a deadline for this item.  With prefix arg remove the deadline.  

`k     (`org-agenda-action')'
     Agenda actions, to set dates for selected items to the cursor date.
     This command also works in the calendar!  The command prompts for
     an additional key:
          m   Mark the entry at point for action.  You can also make entries
              in Org files with `C-c C-x C-k'.
          d   Set the deadline of the marked entry to the date at point.
          s   Schedule the marked entry at the date at point.
          r   Call `org-capture' with the cursor date as default date.
     Press `r' afterward to refresh the agenda and see the effect of the
     command.  

`S-<right>     (`org-agenda-do-date-later')'
     Change the timestamp associated with the current line by one day
     into the future.  If the date is in the past, the first call to
     this command will move it to today.
     With a numeric prefix argument, change it by that many days.  For
     example, `3 6 5 S-<right>' will change it by a year.  With a `C-u'
     prefix, change the time by one hour.  If you immediately repeat
     the command, it will continue to change hours even without the
     prefix arg.  With a double `C-u C-u' prefix, do the same for
     changing minutes.
     The stamp is changed in the original Org file, but the change is
     not directly reflected in the agenda buffer.  Use `r' or `g' to
     update the buffer.  

`S-<left>     (`org-agenda-do-date-earlier')'
     Change the timestamp associated with the current line by one day
     into the past.  

`>     (`org-agenda-date-prompt')'
     Change the timestamp associated with the current line.  The key
     `>' has been chosen, because it is the same as `S-.'  on my
     keyboard.  

`I     (`org-agenda-clock-in')'
     Start the clock on the current item.  If a clock is running
     already, it is stopped first.  

`O     (`org-agenda-clock-out')'
     Stop the previously started clock.  

`X     (`org-agenda-clock-cancel')'
     Cancel the currently running clock.  

`J     (`org-agenda-clock-goto')'
     Jump to the running clock in another window.

Bulk remote editing selected entries
....................................

`m     (`org-agenda-bulk-mark')'
     Mark the entry at point for bulk action.  With prefix arg, mark
     that many successive entries.  

`%     (`org-agenda-bulk-mark-regexp')'
     Mark entries matching a regular expression for bulk action.  

`u     (`org-agenda-bulk-unmark')'
     Unmark entry for bulk action.  

`U     (`org-agenda-bulk-remove-all-marks')'
     Unmark all marked entries for bulk action.  

`B     (`org-agenda-bulk-action')'
     Bulk action: act on all marked entries in the agenda.  This will
     prompt for another key to select the action to be applied.  The
     prefix arg to `B' will be passed through to the `s' and `d'
     commands, to bulk-remove these special timestamps.
          r  Prompt for a single refile target and move all entries.  The entries
             will no longer be in the agenda; refresh (`g') to bring them back.
          $  Archive all selected entries.
          A  Archive entries by moving them to their respective archive siblings.
          t  Change TODO state.  This prompts for a single TODO keyword and
             changes the state of all selected entries, bypassing blocking and
             suppressing logging notes (but not timestamps).
          +  Add a tag to all selected entries.
          -  Remove a tag from all selected entries.
          s  Schedule all items to a new date.  To shift existing schedule dates
             by a fixed number of days, use something starting with double plus
             at the prompt, for example `++8d' or `++2w'.
          S  Reschedule randomly into the coming N days.  N will be prompted for.
             With prefix arg (`C-u B S'), scatter only across weekdays.
          d  Set deadline to a specific date.
          f  Apply a function to marked entries.
             For example, the function below sets the CATEGORY property of the
             entries to web.
             (defun set-category ()
               (interactive "P")
               (let* ((marker (or (org-get-at-bol 'org-hd-marker)
                                  (org-agenda-error)))
                         (buffer (marker-buffer marker)))
                    (with-current-buffer buffer
                      (save-excursion
                        (save-restriction
                          (widen)
                          (goto-char marker)
                          (org-back-to-heading t)
                          (org-set-property "CATEGORY" "web"))))))

Calendar commands
.................

`c     (`org-agenda-goto-calendar')'
     Open the Emacs calendar and move to the date at the agenda cursor.  

`c     (`org-calendar-goto-agenda')'
     When in the calendar, compute and show the Org mode agenda for the
     date at the cursor.  

`i     (`org-agenda-diary-entry')'
     Insert a new entry into the diary, using the date at the cursor
     and (for block entries) the date at the mark.  This will add to
     the Emacs diary file(3), in a way similar to the `i' command in
     the calendar.  The diary file will pop up in another window, where
     you can add the entry.

     If you configure `org-agenda-diary-file' to point to an Org mode
     file, Org will create entries (in Org mode syntax) in that file
     instead.  Most entries will be stored in a date-based outline tree
     that will later make it easy to archive appointments from previous
     months/years.  The tree will be built under an entry with a
     `DATE_TREE' property, or else with years as top-level entries.
     Emacs will prompt you for the entry text--if you specify it, the
     entry will be created in `org-agenda-diary-file' without further
     interaction.  If you directly press <RET> at the prompt without
     typing text, the target file will be shown in another window for
     you to finish the entry there.  See also the `k r' command.  

`M     (`org-agenda-phases-of-moon')'
     Show the phases of the moon for the three months around current
     date.  

`S     (`org-agenda-sunrise-sunset')'
     Show sunrise and sunset times.  The geographical location must be
     set with calendar variables, see the documentation for the Emacs
     calendar.  

`C     (`org-agenda-convert-date')'
     Convert the date at cursor into many other cultural and historic
     calendars.  

`H     (`org-agenda-holidays')'
     Show holidays for three months around the cursor date.

`M-x org-export-icalendar-combine-agenda-files'
     Export a single iCalendar file containing entries from all agenda
     files.  This is a globally available command, and also available
     in the agenda menu.

Exporting to a file
...................

`C-x C-w     (`org-write-agenda')'
     Write the agenda view to a file.  Depending on the extension of
     the selected file name, the view will be exported as HTML
     (extension `.html' or `.htm'), Postscript (extension `.ps'), PDF
     (extension `.pdf'), and plain text (any other extension).  When
     called with a `C-u' prefix argument, immediately open the newly
     created file.  Use the variable `org-agenda-exporter-settings' to
     set options for `ps-print' and for `htmlize' to be used during
     export.

Quit and Exit
.............

`q     (`org-agenda-quit')'
     Quit agenda, remove the agenda buffer.  

`x     (`org-agenda-exit')'
     Exit agenda, remove the agenda buffer and all buffers loaded by
     Emacs for the compilation of the agenda.  Buffers created by the
     user to visit Org files will not be removed.

   ---------- Footnotes ----------

   (1) Only tags filtering will be respected here, effort filtering is
ignored.

   (2) Custom commands can preset a filter by binding the variable
`org-agenda-tag-filter-preset' as an option.  This filter will then be
applied to the view and persist as a basic filter through refreshes and
more secondary filtering.  The filter is a global property of the
entire agenda view--in a block agenda, you should only set this in the
global options section, not in the section of an individual block.

   (3) This file is parsed for the agenda when
`org-agenda-include-diary' is set.


File: org,  Node: Custom agenda views,  Next: Exporting Agenda Views,  Prev: Agenda commands,  Up: Agenda Views

10.6 Custom agenda views
========================

Custom agenda commands serve two purposes: to store and quickly access
frequently used TODO and tags searches, and to create special composite
agenda buffers.  Custom agenda commands will be accessible through the
dispatcher (*note Agenda dispatcher::), just like the default commands.

* Menu:

* Storing searches::            Type once, use often
* Block agenda::                All the stuff you need in a single buffer
* Setting Options::             Changing the rules


File: org,  Node: Storing searches,  Next: Block agenda,  Prev: Custom agenda views,  Up: Custom agenda views

10.6.1 Storing searches
-----------------------

The first application of custom searches is the definition of keyboard
shortcuts for frequently used searches, either creating an agenda
buffer, or a sparse tree (the latter covering of course only the current
buffer).  Custom commands are configured in the variable
`org-agenda-custom-commands'.  You can customize this variable, for
example by pressing `C-c a C'.  You can also directly set it with Emacs
Lisp in `.emacs'.  The following example contains all valid search
types:

     (setq org-agenda-custom-commands
           '(("w" todo "WAITING")
             ("W" todo-tree "WAITING")
             ("u" tags "+boss-urgent")
             ("v" tags-todo "+boss-urgent")
             ("U" tags-tree "+boss-urgent")
             ("f" occur-tree "\\<FIXME\\>")
             ("h" . "HOME+Name tags searches") ; description for "h" prefix
             ("hl" tags "+home+Lisa")
             ("hp" tags "+home+Peter")
             ("hk" tags "+home+Kim")))

The initial string in each entry defines the keys you have to press
after the dispatcher command `C-c a' in order to access the command.
Usually this will be just a single character, but if you have many
similar commands, you can also define two-letter combinations where the
first character is the same in several combinations and serves as a
prefix key(1).  The second parameter is the search type, followed by
the string or regular expression to be used for the matching.  The
example above will therefore define:

`C-c a w'
     as a global search for TODO entries with `WAITING' as the TODO
     keyword

`C-c a W'
     as the same search, but only in the current buffer and displaying
     the results as a sparse tree

`C-c a u'
     as a global tags search for headlines marked `:boss:' but not
     `:urgent:'

`C-c a v'
     as the same search as `C-c a u', but limiting the search to
     headlines that are also TODO items

`C-c a U'
     as the same search as `C-c a u', but only in the current buffer and
     displaying the result as a sparse tree

`C-c a f'
     to create a sparse tree (again: current buffer only) with all
     entries containing the word `FIXME'

`C-c a h'
     as a prefix command for a HOME tags search where you have to press
     an additional key (`l', `p' or `k') to select a name (Lisa, Peter,
     or Kim) as additional tag to match.

   ---------- Footnotes ----------

   (1) You can provide a description for a prefix key by inserting a
cons cell with the prefix and the description.


File: org,  Node: Block agenda,  Next: Setting Options,  Prev: Storing searches,  Up: Custom agenda views

10.6.2 Block agenda
-------------------

Another possibility is the construction of agenda views that comprise
the results of _several_ commands, each of which creates a block in the
agenda buffer.  The available commands include `agenda' for the daily
or weekly agenda (as created with `C-c a a'), `alltodo' for the global
TODO list (as constructed with `C-c a t'), and the matching commands
discussed above: `todo', `tags', and `tags-todo'.  Here are two
examples:

     (setq org-agenda-custom-commands
           '(("h" "Agenda and Home-related tasks"
              ((agenda "")
               (tags-todo "home")
               (tags "garden")))
             ("o" "Agenda and Office-related tasks"
              ((agenda "")
               (tags-todo "work")
               (tags "office")))))

This will define `C-c a h' to create a multi-block view for stuff you
need to attend to at home.  The resulting agenda buffer will contain
your agenda for the current week, all TODO items that carry the tag
`home', and also all lines tagged with `garden'.  Finally the command
`C-c a o' provides a similar view for office tasks.


File: org,  Node: Setting Options,  Prev: Block agenda,  Up: Custom agenda views

10.6.3 Setting options for custom commands
------------------------------------------

Org mode contains a number of variables regulating agenda construction
and display.  The global variables define the behavior for all agenda
commands, including the custom commands.  However, if you want to change
some settings just for a single custom view, you can do so.  Setting
options requires inserting a list of variable names and values at the
right spot in `org-agenda-custom-commands'.  For example:

     (setq org-agenda-custom-commands
           '(("w" todo "WAITING"
              ((org-agenda-sorting-strategy '(priority-down))
               (org-agenda-prefix-format "  Mixed: ")))
             ("U" tags-tree "+boss-urgent"
              ((org-show-following-heading nil)
               (org-show-hierarchy-above nil)))
             ("N" search ""
              ((org-agenda-files '("~org/notes.org"))
               (org-agenda-text-search-extra-files nil)))))

Now the `C-c a w' command will sort the collected entries only by
priority, and the prefix format is modified to just say `  Mixed: '
instead of giving the category of the entry.  The sparse tags tree of
`C-c a U' will now turn out ultra-compact, because neither the headline
hierarchy above the match, nor the headline following the match will be
shown.  The command `C-c a N' will do a text search limited to only a
single file.

   For command sets creating a block agenda,
`org-agenda-custom-commands' has two separate spots for setting
options.  You can add options that should be valid for just a single
command in the set, and options that should be valid for all commands in
the set.  The former are just added to the command entry; the latter
must come after the list of command entries.  Going back to the block
agenda example (*note Block agenda::), let's change the sorting strategy
for the `C-c a h' commands to `priority-down', but let's sort the
results for GARDEN tags query in the opposite order, `priority-up'.
This would look like this:

     (setq org-agenda-custom-commands
           '(("h" "Agenda and Home-related tasks"
              ((agenda)
               (tags-todo "home")
               (tags "garden"
                     ((org-agenda-sorting-strategy '(priority-up)))))
              ((org-agenda-sorting-strategy '(priority-down))))
             ("o" "Agenda and Office-related tasks"
              ((agenda)
               (tags-todo "work")
               (tags "office")))))

   As you see, the values and parentheses setting is a little complex.
When in doubt, use the customize interface to set this variable--it
fully supports its structure.  Just one caveat: when setting options in
this interface, the _values_ are just Lisp expressions.  So if the
value is a string, you need to add the double-quotes around the value
yourself.


File: org,  Node: Exporting Agenda Views,  Next: Agenda column view,  Prev: Custom agenda views,  Up: Agenda Views

10.7 Exporting Agenda Views
===========================

If you are away from your computer, it can be very useful to have a
printed version of some agenda views to carry around.  Org mode can
export custom agenda views as plain text, HTML(1), Postscript, PDF(2),
and iCalendar files.  If you want to do this only occasionally, use the
command

`C-x C-w     (`org-write-agenda')'
     Write the agenda view to a file.  Depending on the extension of
     the selected file name, the view will be exported as HTML
     (extension `.html' or `.htm'), Postscript (extension `.ps'),
     iCalendar (extension `.ics'), or plain text (any other extension).
     Use the variable `org-agenda-exporter-settings' to set options for
     `ps-print' and for `htmlize' to be used during export, for example

          (setq org-agenda-exporter-settings
                '((ps-number-of-columns 2)
                  (ps-landscape-mode t)
                  (org-agenda-add-entry-text-maxlines 5)
                  (htmlize-output-type 'css)))

   If you need to export certain agenda views frequently, you can
associate any custom agenda command with a list of output file names
(3).  Here is an example that first defines custom commands for the
agenda and the global TODO list, together with a number of files to
which to export them.  Then we define two block agenda commands and
specify file names for them as well.  File names can be relative to the
current working directory, or absolute.

     (setq org-agenda-custom-commands
           '(("X" agenda "" nil ("agenda.html" "agenda.ps"))
             ("Y" alltodo "" nil ("todo.html" "todo.txt" "todo.ps"))
             ("h" "Agenda and Home-related tasks"
              ((agenda "")
               (tags-todo "home")
               (tags "garden"))
              nil
              ("~/views/home.html"))
             ("o" "Agenda and Office-related tasks"
              ((agenda)
               (tags-todo "work")
               (tags "office"))
              nil
              ("~/views/office.ps" "~/calendars/office.ics"))))

   The extension of the file name determines the type of export.  If it
is `.html', Org mode will use the `htmlize.el' package to convert the
buffer to HTML and save it to this file name.  If the extension is
`.ps', `ps-print-buffer-with-faces' is used to produce Postscript
output.  If the extension is `.ics', iCalendar export is run export
over all files that were used to construct the agenda, and limit the
export to entries listed in the agenda.  Any other extension produces a
plain ASCII file.

   The export files are _not_ created when you use one of those
commands interactively because this might use too much overhead.
Instead, there is a special command to produce _all_ specified files in
one step:

`C-c a e     (`org-store-agenda-views')'
     Export all agenda views that have export file names associated with
     them.

   You can use the options section of the custom agenda commands to also
set options for the export commands.  For example:

     (setq org-agenda-custom-commands
           '(("X" agenda ""
              ((ps-number-of-columns 2)
               (ps-landscape-mode t)
               (org-agenda-prefix-format " [ ] ")
               (org-agenda-with-colors nil)
               (org-agenda-remove-tags t))
              ("theagenda.ps"))))

This command sets two options for the Postscript exporter, to make it
print in two columns in landscape format--the resulting page can be cut
in two and then used in a paper agenda.  The remaining settings modify
the agenda prefix to omit category and scheduling information, and
instead include a checkbox to check off items.  We also remove the tags
to make the lines compact, and we don't want to use colors for the
black-and-white printer.  Settings specified in
`org-agenda-exporter-settings' will also apply, but the settings in
`org-agenda-custom-commands' take precedence.

From the command line you may also use
     emacs -eval (org-batch-store-agenda-views) -kill
   or, if you need to modify some parameters(4)
     emacs -eval '(org-batch-store-agenda-views                      \
                   org-agenda-span (quote month)                     \
                   org-agenda-start-day "2007-11-01"                 \
                   org-agenda-include-diary nil                      \
                   org-agenda-files (quote ("~/org/project.org")))'  \
           -kill
   which will create the agenda views restricted to the file
`~/org/project.org', without diary entries and with a 30-day extent.

   You can also extract agenda information in a way that allows further
processing by other programs.  See *note Extracting agenda
information::, for more information.

   ---------- Footnotes ----------

   (1) You need to install Hrvoje Niksic's `htmlize.el'.

   (2) To create PDF output, the ghostscript `ps2pdf' utility must be
installed on the system.  Selecting a PDF file will also create the
postscript file.

   (3) If you want to store standard views like the weekly agenda or
the global TODO list as well, you need to define custom commands for
them in order to be able to specify file names.

   (4) Quoting depends on the system you use, please check the FAQ for
examples.


File: org,  Node: Agenda column view,  Prev: Exporting Agenda Views,  Up: Agenda Views

10.8 Using column view in the agenda
====================================

Column view (*note Column view::) is normally used to view and edit
properties embedded in the hierarchical structure of an Org file.  It
can be quite useful to use column view also from the agenda, where
entries are collected by certain criteria.

`C-c C-x C-c     (`org-agenda-columns')'
     Turn on column view in the agenda.

   To understand how to use this properly, it is important to realize
that the entries in the agenda are no longer in their proper outline
environment.  This causes the following issues:

  1. Org needs to make a decision which `COLUMNS' format to use.  Since
     the entries in the agenda are collected from different files, and
     different files may have different `COLUMNS' formats, this is a
     non-trivial problem.  Org first checks if the variable
     `org-agenda-overriding-columns-format' is currently set, and if
     so, takes the format from there.  Otherwise it takes the format
     associated with the first item in the agenda, or, if that item
     does not have a specific format (defined in a property, or in its
     file), it uses `org-columns-default-format'.

  2. If any of the columns has a summary type defined (*note Column
     attributes::), turning on column view in the agenda will visit all
     relevant agenda files and make sure that the computations of this
     property are up to date.  This is also true for the special
     `CLOCKSUM' property.  Org will then sum the values displayed in
     the agenda.  In the daily/weekly agenda, the sums will cover a
     single day; in all other views they cover the entire block.  It is
     vital to realize that the agenda may show the same entry _twice_
     (for example as scheduled and as a deadline), and it may show two
     entries from the same hierarchy (for example a _parent_ and its
     _child_).  In these cases, the summation in the agenda will lead
     to incorrect results because some values will count double.

  3. When the column view in the agenda shows the `CLOCKSUM', that is
     always the entire clocked time for this item.  So even in the
     daily/weekly agenda, the clocksum listed in column view may
     originate from times outside the current view.  This has the
     advantage that you can compare these values with a column listing
     the planned total effort for a task--one of the major applications
     for column view in the agenda.  If you want information about
     clocked time in the displayed period use clock table mode (press
     `R' in the agenda).


File: org,  Node: Markup,  Next: Exporting,  Prev: Agenda Views,  Up: Top

11 Markup for rich export
*************************

When exporting Org mode documents, the exporter tries to reflect the
structure of the document as accurately as possible in the backend.
Since export targets like HTML, LaTeX, or DocBook allow much richer
formatting, Org mode has rules on how to prepare text for rich export.
This section summarizes the markup rules used in an Org mode buffer.

* Menu:

* Structural markup elements::  The basic structure as seen by the exporter
* Images and tables::           Tables and Images will be included
* Literal examples::            Source code examples with special formatting
* Include files::               Include additional files into a document
* Index entries::               Making an index
* Macro replacement::           Use macros to create complex output
* Embedded LaTeX::           LaTeX can be freely used inside Org documents


File: org,  Node: Structural markup elements,  Next: Images and tables,  Prev: Markup,  Up: Markup

11.1 Structural markup elements
===============================

* Menu:

* Document title::              Where the title is taken from
* Headings and sections::       The document structure as seen by the exporter
* Table of contents::           The if and where of the table of contents
* Initial text::                Text before the first heading?
* Lists::                       Lists
* Paragraphs::                  Paragraphs
* Footnote markup::             Footnotes
* Emphasis and monospace::      Bold, italic, etc.
* Horizontal rules::            Make a line
* Comment lines::               What will *not* be exported


File: org,  Node: Document title,  Next: Headings and sections,  Prev: Structural markup elements,  Up: Structural markup elements

Document title
--------------

The title of the exported document is taken from the special line

     #+TITLE: This is the title of the document

If this line does not exist, the title is derived from the first
non-empty, non-comment line in the buffer.  If no such line exists, or
if you have turned off exporting of the text before the first headline
(see below), the title will be the file name without extension.

   If you are exporting only a subtree by marking is as the region, the
heading of the subtree will become the title of the document.  If the
subtree has a property `EXPORT_TITLE', that will take precedence.


File: org,  Node: Headings and sections,  Next: Table of contents,  Prev: Document title,  Up: Structural markup elements

Headings and sections
---------------------

The outline structure of the document as described in *note Document
Structure::, forms the basis for defining sections of the exported
document.  However, since the outline structure is also used for (for
example) lists of tasks, only the first three outline levels will be
used as headings.  Deeper levels will become itemized lists.  You can
change the location of this switch globally by setting the variable
`org-export-headline-levels', or on a per-file basis with a line

     #+OPTIONS: H:4


File: org,  Node: Table of contents,  Next: Initial text,  Prev: Headings and sections,  Up: Structural markup elements

Table of contents
-----------------

The table of contents is normally inserted directly before the first
headline of the file.  If you would like to get it to a different
location, insert the string `[TABLE-OF-CONTENTS]' on a line by itself
at the desired location.  The depth of the table of contents is by
default the same as the number of headline levels, but you can choose a
smaller number, or turn off the table of contents entirely, by
configuring the variable `org-export-with-toc', or on a per-file basis
with a line like

     #+OPTIONS: toc:2          (only to two levels in TOC)
     #+OPTIONS: toc:nil        (no TOC at all)


File: org,  Node: Initial text,  Next: Lists,  Prev: Table of contents,  Up: Structural markup elements

Text before the first headline
------------------------------

Org mode normally exports the text before the first headline, and even
uses the first line as the document title.  The text will be fully
marked up.  If you need to include literal HTML, LaTeX, or DocBook
code, use the special constructs described below in the sections for
the individual exporters.

   Some people like to use the space before the first headline for
setup and internal links and therefore would like to control the
exported text before the first headline in a different way.  You can do
so by setting the variable `org-export-skip-text-before-1st-heading' to
`t'.  On a per-file basis, you can get the same effect with `#+OPTIONS:
skip:t'.

If you still want to have some text before the first headline, use the
`#+TEXT' construct:

     #+OPTIONS: skip:t
     #+TEXT: This text will go before the *first* headline.
     #+TEXT: [TABLE-OF-CONTENTS]
     #+TEXT: This goes between the table of contents and the *first* headline


File: org,  Node: Lists,  Next: Paragraphs,  Prev: Initial text,  Up: Structural markup elements

Lists
-----

Plain lists as described in *note Plain lists::, are translated to the
backend's syntax for such lists.  Most backends support unordered,
ordered, and description lists.


File: org,  Node: Paragraphs,  Next: Footnote markup,  Prev: Lists,  Up: Structural markup elements

Paragraphs, line breaks, and quoting
------------------------------------

Paragraphs are separated by at least one empty line.  If you need to
enforce a line break within a paragraph, use `\\' at the end of a line.

   To keep the line breaks in a region, but otherwise use normal
formatting, you can use this construct, which can also be used to
format poetry.

     #+BEGIN_VERSE
      Great clouds overhead
      Tiny black birds rise and fall
      Snow covers Emacs

          -- AlexSchroeder
     #+END_VERSE

   When quoting a passage from another document, it is customary to
format this as a paragraph that is indented on both the left and the
right margin.  You can include quotations in Org mode documents like
this:

     #+BEGIN_QUOTE
     Everything should be made as simple as possible,
     but not any simpler -- Albert Einstein
     #+END_QUOTE

   If you would like to center some text, do it like this: 
     #+BEGIN_CENTER
     Everything should be made as simple as possible, \\
     but not any simpler
     #+END_CENTER


File: org,  Node: Footnote markup,  Next: Emphasis and monospace,  Prev: Paragraphs,  Up: Structural markup elements

Footnote markup
---------------

Footnotes defined in the way described in *note Footnotes::, will be
exported by all backends.  Org allows multiple references to the same
note, and multiple footnotes side by side.


File: org,  Node: Emphasis and monospace,  Next: Horizontal rules,  Prev: Footnote markup,  Up: Structural markup elements

Emphasis and monospace
----------------------

You can make words *bold*, /italic/, _underlined_, `=code=' and
`~verbatim~', and, if you must, `+strike-through+'.  Text in the code
and verbatim string is not processed for Org mode specific syntax; it
is exported verbatim.


File: org,  Node: Horizontal rules,  Next: Comment lines,  Prev: Emphasis and monospace,  Up: Structural markup elements

Horizontal rules
----------------

A line consisting of only dashes, and at least 5 of them, will be
exported as a horizontal line (`<hr/>' in HTML and `\hrule' in LaTeX).


File: org,  Node: Comment lines,  Prev: Horizontal rules,  Up: Structural markup elements

Comment lines
-------------

Lines starting with `#' in column zero are treated as comments and will
never be exported.  If you want an indented line to be treated as a
comment, start it with `#+ '.  Also entire subtrees starting with the
word `COMMENT' will never be exported.  Finally, regions surrounded by
`#+BEGIN_COMMENT' ... `#+END_COMMENT' will not be exported.

`C-c ;'
     Toggle the COMMENT keyword at the beginning of an entry.


File: org,  Node: Images and tables,  Next: Literal examples,  Prev: Structural markup elements,  Up: Markup

11.2 Images and Tables
======================

Both the native Org mode tables (*note Tables::) and tables formatted
with the `table.el' package will be exported properly.  For Org mode
tables, the lines before the first horizontal separator line will
become table header lines.  You can use the following lines somewhere
before the table to assign a caption and a label for cross references,
and in the text you can refer to the object with `\ref{tab:basic-data}':

     #+CAPTION: This is the caption for the next table (or link)
     #+LABEL:   tbl:basic-data
        | ... | ...|
        |-----|----|

   Optionally, the caption can take the form:
     #+CAPTION: [Caption for list of figures]{Caption for table (or link).}

   Some backends (HTML, LaTeX, and DocBook) allow you to directly
include images into the exported document.  Org does this, if a link to
an image files does not have a description part, for example
`[[./img/a.jpg]]'.  If you wish to define a caption for the image and
maybe a label for internal cross references, make sure that the link is
on a line by itself and precede it with `#+CAPTION' and `#+LABEL' as
follows:

     #+CAPTION: This is the caption for the next figure link (or table)
     #+LABEL:   fig:SED-HR4049
     [[./img/a.jpg]]

   You may also define additional attributes for the figure.  As this is
backend-specific, see the sections about the individual backends for
more information.

   *Note the discussion of image links: Handling links.


File: org,  Node: Literal examples,  Next: Include files,  Prev: Images and tables,  Up: Markup

11.3 Literal examples
=====================

You can include literal examples that should not be subjected to
markup.  Such examples will be typeset in monospace, so this is well
suited for source code and similar examples.  

     #+BEGIN_EXAMPLE
     Some example from a text file.
     #+END_EXAMPLE

   Note that such blocks may be indented in order to align nicely with
indented text and in particular with plain list structure (*note Plain
lists::).  For simplicity when using small examples, you can also start
the example lines with a colon followed by a space.  There may also be
additional whitespace before the colon:

     Here is an example
        : Some example from a text file.

   If the example is source code from a programming language, or any
other text that can be marked up by font-lock in Emacs, you can ask for
the example to look like the fontified Emacs buffer(1).  This is done
with the `src' block, where you also need to specify the name of the
major mode that should be used to fontify the example(2), see *note
Easy Templates:: for shortcuts to easily insert code blocks.  

     #+BEGIN_SRC emacs-lisp
       (defun org-xor (a b)
          "Exclusive or."
          (if a (not b) b))
     #+END_SRC

   Both in `example' and in `src' snippets, you can add a `-n' switch
to the end of the `BEGIN' line, to get the lines of the example
numbered.  If you use a `+n' switch, the numbering from the previous
numbered snippet will be continued in the current one.  In literal
examples, Org will interpret strings like `(ref:name)' as labels, and
use them as targets for special hyperlinks like `[[(name)]]' (i.e. the
reference name enclosed in single parenthesis).  In HTML, hovering the
mouse over such a link will remote-highlight the corresponding code
line, which is kind of cool.

   You can also add a `-r' switch which removes the labels from the
source code(3).  With the `-n' switch, links to these references will
be labeled by the line numbers from the code listing, otherwise links
will use the labels with no parentheses.  Here is an example:

     #+BEGIN_SRC emacs-lisp -n -r
     (save-excursion                  (ref:sc)
        (goto-char (point-min))       (ref:jump)
     #+END_SRC
     In line [[(sc)]] we remember the current position.  [[(jump)][Line (jump)]]
     jumps to point-min.

   If the syntax for the label format conflicts with the language
syntax, use a `-l' switch to change the format, for example
`#+BEGIN_SRC pascal -n -r -l "((%s))"'.  See also the variable
`org-coderef-label-format'.

   HTML export also allows examples to be published as text areas
(*note Text areas in HTML export::).

   Because the `#+BEGIN_...' and `#+END_...' patterns need to be added
so often, shortcuts are provided using the Easy Templates facility
(*note Easy Templates::).

`C-c ''
     Edit the source code example at point in its native mode.  This
     works by switching to a temporary buffer with the source code.
     You need to exit by pressing `C-c '' again(4).  The edited version
     will then replace the old version in the Org buffer.  Fixed-width
     regions (where each line starts with a colon followed by a space)
     will be edited using `artist-mode'(5) to allow creating ASCII
     drawings easily.  Using this command in an empty line will create
     a new fixed-width region.  

`C-c l'
     Calling `org-store-link' while editing a source code example in a
     temporary buffer created with `C-c '' will prompt for a label.
     Make sure that it is unique in the current buffer, and insert it
     with the proper formatting like `(ref:label)' at the end of the
     current line.  Then the label is stored as a link `(label)', for
     retrieval with `C-c C-l'.

   ---------- Footnotes ----------

   (1) This works automatically for the HTML backend (it requires
version 1.34 of the `htmlize.el' package, which is distributed with
Org).  Fontified code chunks in LaTeX can be achieved using either the
listings or the minted (http://code.google.com/p/minted) package.  To
use listings, turn on the variable `org-export-latex-listings' and
ensure that the listings package is included by the LaTeX header (e.g.
by configuring `org-export-latex-packages-alist').  See the listings
documentation for configuration options, including obtaining colored
output.  For minted it is necessary to install the program pygments
(http://pygments.org), in addition to setting
`org-export-latex-minted', ensuring that the minted package is included
by the LaTeX header, and ensuring that the `-shell-escape' option is
passed to `pdflatex' (see `org-latex-to-pdf-process').  See the
documentation of the variables `org-export-latex-listings' and
`org-export-latex-minted' for further details.

   (2) Code in `src' blocks may also be evaluated either interactively
or on export.  See *note Working With Source Code:: for more
information on evaluating code blocks.

   (3) Adding `-k' to `-n -r' will keep the labels in the source code
while using line numbers for the links, which might be useful to
explain those in an Org mode example code.

   (4) Upon exit, lines starting with `*' or `#' will get a comma
prepended, to keep them from being interpreted by Org as outline nodes
or special comments.  These commas will be stripped for editing with
`C-c '', and also for export.

   (5) You may select a different-mode with the variable
`org-edit-fixed-width-region-mode'.


File: org,  Node: Include files,  Next: Index entries,  Prev: Literal examples,  Up: Markup

11.4 Include files
==================

During export, you can include the content of another file.  For
example, to include your `.emacs' file, you could use: 

     #+INCLUDE: "~/.emacs" src emacs-lisp
   The optional second and third parameter are the markup (e.g. `quote',
`example', or `src'), and, if the markup is `src', the language for
formatting the contents.  The markup is optional; if it is not given,
the text will be assumed to be in Org mode format and will be processed
normally.  The include line will also allow additional keyword
parameters `:prefix1' and `:prefix' to specify prefixes for the first
line and for each following line, `:minlevel' in order to get Org mode
content demoted to a specified level, as well as any options accepted
by the selected markup.  For example, to include a file as an item, use

     #+INCLUDE: "~/snippets/xx" :prefix1 "   + " :prefix "     "

   You can also include a portion of a file by specifying a lines range
using the `:lines' parameter.  The line at the upper end of the range
will not be included.  The start and/or the end of the range may be
omitted to use the obvious defaults.

     #+INCLUDE: "~/.emacs" :lines "5-10"   Include lines 5 to 10, 10 excluded
     #+INCLUDE: "~/.emacs" :lines "-10"    Include lines 1 to 10, 10 excluded
     #+INCLUDE: "~/.emacs" :lines "10-"    Include lines from 10 to EOF

`C-c ''
     Visit the include file at point.


File: org,  Node: Index entries,  Next: Macro replacement,  Prev: Include files,  Up: Markup

11.5 Index entries
==================

You can specify entries that will be used for generating an index during
publishing.  This is done by lines starting with `#+INDEX'.  An entry
the contains an exclamation mark will create a sub item.  See *note
Generating an index:: for more information.

     * Curriculum Vitae
     #+INDEX: CV
     #+INDEX: Application!CV


File: org,  Node: Macro replacement,  Next: Embedded LaTeX,  Prev: Index entries,  Up: Markup

11.6 Macro replacement
======================

You can define text snippets with

     #+MACRO: name   replacement text $1, $2 are arguments

which can be referenced anywhere in the document (even in code
examples) with `{{{name(arg1,arg2)}}}'.  In addition to defined macros,
`{{{title}}}', `{{{author}}}', etc., will reference information set by
the `#+TITLE:', `#+AUTHOR:', and similar lines.  Also,
`{{{date(FORMAT)}}}' and `{{{modification-time(FORMAT)}}}' refer to
current date time and to the modification time of the file being
exported, respectively.  FORMAT should be a format string understood by
`format-time-string'.

   Macro expansion takes place during export, and some people use it to
construct complex HTML code.


File: org,  Node: Embedded LaTeX,  Prev: Macro replacement,  Up: Markup

11.7 Embedded LaTeX
===================

Plain ASCII is normally sufficient for almost all note taking.
Exceptions include scientific notes, which often require mathematical
symbols and the occasional formula.  LaTeX(1)  is widely used to
typeset scientific documents.  Org mode supports embedding LaTeX code
into its files, because many academics are used to writing and reading
LaTeX source code, and because it can be readily processed to produce
pretty output for a number of export backends.

* Menu:

* Special symbols::             Greek letters and other symbols
* Subscripts and superscripts::  Simple syntax for raising/lowering text
* LaTeX fragments::             Complex formulas made easy
* Previewing LaTeX fragments::  What will this snippet look like?
* CDLaTeX mode::                Speed up entering of formulas

   ---------- Footnotes ----------

   (1) LaTeX is a macro system based on Donald E. Knuth's TeX system.
Many of the features described here as "LaTeX" are really from TeX, but
for simplicity I am blurring this distinction.


File: org,  Node: Special symbols,  Next: Subscripts and superscripts,  Prev: Embedded LaTeX,  Up: Embedded LaTeX

11.7.1 Special symbols
----------------------

You can use LaTeX macros to insert special symbols like `\alpha' to
indicate the Greek letter, or `\to' to indicate an arrow.  Completion
for these macros is available, just type `\' and maybe a few letters,
and press `M-<TAB>' to see possible completions.  Unlike LaTeX code,
Org mode allows these macros to be present without surrounding math
delimiters, for example:

     Angles are written as Greek letters \alpha, \beta and \gamma.

   During export, these symbols will be transformed into the native
format of the exporter backend.  Strings like `\alpha' will be exported
as `&alpha;' in the HTML output, and as `$\alpha$' in the LaTeX output.
Similarly, `\nbsp' will become `&nbsp;' in HTML and `~' in LaTeX.  If
you need such a symbol inside a word, terminate it like this:
`\Aacute{}stor'.

   A large number of entities is provided, with names taken from both
HTML and LaTeX; see the variable `org-entities' for the complete list.
`\-' is treated as a shy hyphen, and `--', `---', and `...' are all
converted into special commands creating hyphens of different lengths
or a compact set of dots.

   If you would like to see entities displayed as UTF8 characters, use
the following command(1):

`C-c C-x \'
     Toggle display of entities as UTF-8 characters.  This does not
     change the buffer content which remains plain ASCII, but it
     overlays the UTF-8 character for display purposes only.

   ---------- Footnotes ----------

   (1) You can turn this on by default by setting the variable
`org-pretty-entities', or on a per-file base with the `#+STARTUP'
option `entitiespretty'.


File: org,  Node: Subscripts and superscripts,  Next: LaTeX fragments,  Prev: Special symbols,  Up: Embedded LaTeX

11.7.2 Subscripts and superscripts
----------------------------------

Just like in LaTeX, `^' and `_' are used to indicate super- and
subscripts.  Again, these can be used without embedding them in
math-mode delimiters.  To increase the readability of ASCII text, it is
not necessary (but OK) to surround multi-character sub- and superscripts
with curly braces.  For example

     The mass of the sun is M_sun = 1.989 x 10^30 kg.  The radius of
     the sun is R_{sun} = 6.96 x 10^8 m.

   To avoid interpretation as raised or lowered text, you can quote `^'
and `_' with a backslash: `\^' and `\_'.  If you write a text where the
underscore is often used in a different context, Org's convention to
always interpret these as subscripts can get in your way.  Configure the
variable `org-export-with-sub-superscripts' to globally change this
convention, or use, on a per-file basis:

     #+OPTIONS: ^:{}

With this setting, `a_b' will not be interpreted as a subscript, but
`a_{b}' will.

`C-c C-x \'
     In addition to showing entities as UTF-8 characters, this command
     will also format sub- and superscripts in a WYSIWYM way.


File: org,  Node: LaTeX fragments,  Next: Previewing LaTeX fragments,  Prev: Subscripts and superscripts,  Up: Embedded LaTeX

11.7.3 LaTeX fragments
----------------------

Going beyond symbols and sub- and superscripts, a full formula language
is needed.  Org mode can contain LaTeX math fragments, and it supports
ways to process these for several export backends.  When exporting to
LaTeX, the code is obviously left as it is.  When exporting to HTML,
Org invokes the MathJax library (http://www.mathjax.org) (*note Math
formatting in HTML export::) to process and display the math(1).
Finally, it can also process the mathematical expressions into
images(2)  that can be displayed in a browser or in DocBook documents.

   LaTeX fragments don't need any special marking at all.  The following
snippets will be identified as LaTeX source code:
   * Environments of any kind(3).  The only requirement is that the
     `\begin' statement appears on a new line, preceded by only
     whitespace.

   * Text within the usual LaTeX math delimiters.  To avoid conflicts
     with currency specifications, single `$' characters are only
     recognized as math delimiters if the enclosed text contains at
     most two line breaks, is directly attached to the `$' characters
     with no whitespace in between, and if the closing `$' is followed
     by whitespace, punctuation or a dash.  For the other delimiters,
     there is no such restriction, so when in doubt, use `\(...\)' as
     inline math delimiters.

For example:

     \begin{equation}                          % arbitrary environments,
     x=\sqrt{b}                                % even tables, figures
     \end{equation}                            % etc

     If $a^2=b$ and \( b=2 \), then the solution must be
     either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \].

If you need any of the delimiter ASCII sequences for other purposes, you
can configure the option `org-format-latex-options' to deselect the
ones you do not wish to have interpreted by the LaTeX converter.

   LaTeX processing can be configured with the variable
`org-export-with-LaTeX-fragments'.  The default setting is `t' which
means `MathJax' for HTML, and no processing for DocBook, ASCII and
LaTeX backends.  You can also set this variable on a per-file basis
using one of these lines:

     #+OPTIONS: LaTeX:t          Do the right thing automatically (MathJax)
     #+OPTIONS: LaTeX:dvipng     Force using dvipng images
     #+OPTIONS: LaTeX:nil        Do not process LaTeX fragments at all
     #+OPTIONS: LaTeX:verbatim   Verbatim export, for jsMath or so

   ---------- Footnotes ----------

   (1) If you plan to use this regularly or on pages with significant
page views, you should install `MathJax' on your own server in order to
limit the load of our server.

   (2) For this to work you need to be on a system with a working LaTeX
installation.  You also need the `dvipng' program, available at
`http://sourceforge.net/projects/dvipng/'.  The LaTeX header that will
be used when processing a fragment can be configured with the variable
`org-format-latex-header'.

   (3) When `MathJax' is used, only the environment recognized by
`MathJax' will be processed.  When `dvipng' is used to create images,
any LaTeX environments will be handled.


File: org,  Node: Previewing LaTeX fragments,  Next: CDLaTeX mode,  Prev: LaTeX fragments,  Up: Embedded LaTeX

11.7.4 Previewing LaTeX fragments
---------------------------------

If you have `dvipng' installed, LaTeX fragments can be processed to
produce preview images of the typeset expressions:

`C-c C-x C-l'
     Produce a preview image of the LaTeX fragment at point and overlay
     it over the source code.  If there is no fragment at point,
     process all fragments in the current entry (between two
     headlines).  When called with a prefix argument, process the
     entire subtree.  When called with two prefix arguments, or when
     the cursor is before the first headline, process the entire buffer.  

`C-c C-c'
     Remove the overlay preview images.

   You can customize the variable `org-format-latex-options' to
influence some aspects of the preview.  In particular, the `:scale'
(and for HTML export, `:html-scale') property can be used to adjust the
size of the preview images.


File: org,  Node: CDLaTeX mode,  Prev: Previewing LaTeX fragments,  Up: Embedded LaTeX

11.7.5 Using CDLaTeX to enter math
----------------------------------

CDLaTeX mode is a minor mode that is normally used in combination with a
major LaTeX mode like AUCTeX in order to speed-up insertion of
environments and math templates.  Inside Org mode, you can make use of
some of the features of CDLaTeX mode.  You need to install `cdlatex.el'
and `texmathp.el' (the latter comes also with AUCTeX) from
`http://www.astro.uva.nl/~dominik/Tools/cdlatex'.  Don't use CDLaTeX
mode itself under Org mode, but use the light version
`org-cdlatex-mode' that comes as part of Org mode.  Turn it on for the
current buffer with `M-x org-cdlatex-mode', or for all Org files with

     (add-hook 'org-mode-hook 'turn-on-org-cdlatex)

   When this mode is enabled, the following features are present (for
more details see the documentation of CDLaTeX mode):
   * Environment templates can be inserted with `C-c {'.

   * The <TAB> key will do template expansion if the cursor is inside a
     LaTeX fragment(1).  For example, <TAB> will expand `fr' to
     `\frac{}{}' and position the cursor correctly inside the first
     brace.  Another <TAB> will get you into the second brace.  Even
     outside fragments, <TAB> will expand environment abbreviations at
     the beginning of a line.  For example, if you write `equ' at the
     beginning of a line and press <TAB>, this abbreviation will be
     expanded to an `equation' environment.  To get a list of all
     abbreviations, type `M-x cdlatex-command-help'.

   * Pressing `_' and `^' inside a LaTeX fragment will insert these
     characters together with a pair of braces.  If you use <TAB> to
     move out of the braces, and if the braces surround only a single
     character or macro, they are removed again (depending on the
     variable `cdlatex-simplify-sub-super-scripts').

   * Pressing the backquote ``' followed by a character inserts math
     macros, also outside LaTeX fragments.  If you wait more than 1.5
     seconds after the backquote, a help window will pop up.

   * Pressing the single-quote `'' followed by another character
     modifies the symbol before point with an accent or a font.  If you
     wait more than 1.5 seconds after the single-quote, a help window
     will pop up.  Character modification will work only inside LaTeX
     fragments; outside the quote is normal.

   ---------- Footnotes ----------

   (1) Org mode has a method to test if the cursor is inside such a
fragment, see the documentation of the function
`org-inside-LaTeX-fragment-p'.


File: org,  Node: Exporting,  Next: Publishing,  Prev: Markup,  Up: Top

12 Exporting
************

Org mode documents can be exported into a variety of other formats.  For
printing and sharing of notes, ASCII export produces a readable and
simple version of an Org file.  HTML export allows you to publish a
notes file on the web, while the XOXO format provides a solid base for
exchange with a broad range of other applications.  LaTeX export lets
you use Org mode and its structured editing functions to easily create
LaTeX files.  DocBook export makes it possible to convert Org files to
many other formats using DocBook tools.  OpenDocument Text (ODT) export
allows seamless collaboration across organizational boundaries.  For
project management you can create gantt and resource charts by using
TaskJuggler export.  To incorporate entries with associated times like
deadlines or appointments into a desktop calendar program like iCal,
Org mode can also produce extracts in the iCalendar format.  Currently,
Org mode only supports export, not import of these different formats.

   Org supports export of selected regions when `transient-mark-mode' is
enabled (default in Emacs 23).

* Menu:

* Selective export::            Using tags to select and exclude trees
* Export options::              Per-file export settings
* The export dispatcher::       How to access exporter commands
* ASCII/Latin-1/UTF-8 export::  Exporting to flat files with encoding
* HTML export::                 Exporting to HTML
* LaTeX and PDF export::     Exporting to LaTeX, and processing to PDF
* DocBook export::              Exporting to DocBook
* OpenDocument Text export::    Exporting to OpenDocument Text
* TaskJuggler export::          Exporting to TaskJuggler
* Freemind export::             Exporting to Freemind mind maps
* XOXO export::                 Exporting to XOXO
* iCalendar export::            Exporting in iCalendar format


File: org,  Node: Selective export,  Next: Export options,  Prev: Exporting,  Up: Exporting

12.1 Selective export
=====================

You may use tags to select the parts of a document that should be
exported, or to exclude parts from export.  This behavior is governed
by two variables: `org-export-select-tags' and
`org-export-exclude-tags', respectively defaulting to `'(:export:)' and
`'(:noexport:)'.

  1. Org first checks if any of the _select_ tags is present in the
     buffer.  If yes, all trees that do not carry one of these tags
     will be excluded.  If a selected tree is a subtree, the heading
     hierarchy above it will also be selected for export, but not the
     text below those headings.

  2. If none of the select tags is found, the whole buffer will be
     selected for export.

  3. Finally, all subtrees that are marked by any of the _exclude_ tags
     will be removed from the export buffer.

   The variable `org-export-with-tasks' can be configured to select
which kind of tasks should be included for export.  See the docstring
of the variable for more information.


File: org,  Node: Export options,  Next: The export dispatcher,  Prev: Selective export,  Up: Exporting

12.2 Export options
===================

The exporter recognizes special lines in the buffer which provide
additional information.  These lines may be put anywhere in the file.
The whole set of lines can be inserted into the buffer with `C-c C-e
t'.  For individual lines, a good way to make sure the keyword is
correct is to type `#+' and then use `M-<TAB>' completion (*note
Completion::).   For a summary of other in-buffer settings not
specifically related to export, see *note In-buffer settings::.  In
particular, note that you can place commonly-used (export) options in a
separate file which can be included using `#+SETUPFILE'.

`C-c C-e t     (`org-insert-export-options-template')'
     Insert template with export options, see example below.

     #+TITLE:       the title to be shown (default is the buffer name)
     #+AUTHOR:      the author (default taken from `user-full-name')
     #+DATE:        a date, an Org timestamp(1), or a format string for `format-time-string'
     #+EMAIL:       his/her email address (default from `user-mail-address')
     #+DESCRIPTION: the page description, e.g. for the XHTML meta tag
     #+KEYWORDS:    the page keywords, e.g. for the XHTML meta tag
     #+LANGUAGE:    language for HTML, e.g. `en' (`org-export-default-language')
     #+TEXT:        Some descriptive text to be inserted at the beginning.
     #+TEXT:        Several lines may be given.
     #+OPTIONS:     H:2 num:t toc:t \n:nil @:t ::t |:t ^:t f:t TeX:t ...
     #+BIND:        lisp-var lisp-val, e.g.: `org-export-latex-low-levels itemize'
                    You need to confirm using these, or configure `org-export-allow-BIND'
     #+LINK_UP:     the ``up'' link of an exported page
     #+LINK_HOME:   the ``home'' link of an exported page
     #+LATEX_HEADER: extra line(s) for the LaTeX header, like \usepackage{xyz}
     #+EXPORT_SELECT_TAGS:   Tags that select a tree for export
     #+EXPORT_EXCLUDE_TAGS:  Tags that exclude a tree from export
     #+XSLT:        the XSLT stylesheet used by DocBook exporter to generate FO file

The `#+OPTIONS' line is a compact(2) form to specify export settings.
Here you can: 
     H:         set the number of headline levels for export
     num:       turn on/off section-numbers
     toc:       turn on/off table of contents, or set level limit (integer)
     \n:        turn on/off line-break-preservation (DOES NOT WORK)
     @:         turn on/off quoted HTML tags
     ::         turn on/off fixed-width sections
     |:         turn on/off tables
     ^:         turn on/off TeX-like syntax for sub- and superscripts.  If
                you write "^:{}", `a_{b}' will be interpreted, but
                the simple `a_b' will be left as it is.
     -:         turn on/off conversion of special strings.
     f:         turn on/off footnotes like this[1].
     todo:      turn on/off inclusion of TODO keywords into exported text
     tasks:     turn on/off inclusion of tasks (TODO items), can be nil to remove
                all tasks, `todo' to remove DONE tasks, or list of kwds to keep
     pri:       turn on/off priority cookies
     tags:      turn on/off inclusion of tags, may also be `not-in-toc'
     <:         turn on/off inclusion of any time/date stamps like DEADLINES
     *:         turn on/off emphasized text (bold, italic, underlined)
     TeX:       turn on/off simple TeX macros in plain text
     LaTeX:     configure export of LaTeX fragments.  Default `auto'
     skip:      turn on/off skipping the text before the first heading
     author:    turn on/off inclusion of author name/email into exported file
     email:     turn on/off inclusion of author email into exported file
     creator:   turn on/off inclusion of creator info into exported file
     timestamp: turn on/off inclusion creation time into exported file
     d:         turn on/off inclusion of drawers
   These options take effect in both the HTML and LaTeX export, except
for `TeX' and `LaTeX' options, which are respectively `t' and `nil' for
the LaTeX export.

   The default values for these and many other options are given by a
set of variables.  For a list of such variables, the corresponding
OPTIONS keys and also the publishing keys (*note Project alist::), see
the constant `org-export-plist-vars'.

   When exporting only a single subtree by selecting it with `C-c @'
before calling an export command, the subtree can overrule some of the
file's export settings with properties `EXPORT_FILE_NAME',
`EXPORT_TITLE', `EXPORT_TEXT', `EXPORT_AUTHOR', `EXPORT_DATE', and
`EXPORT_OPTIONS'.

   ---------- Footnotes ----------

   (1) `org-export-date-timestamp-format' defines how this timestamp
will be exported.

   (2) If you want to configure many options this way, you can use
several `#+OPTIONS' lines.


File: org,  Node: The export dispatcher,  Next: ASCII/Latin-1/UTF-8 export,  Prev: Export options,  Up: Exporting

12.3 The export dispatcher
==========================

All export commands can be reached using the export dispatcher, which
is a prefix key that prompts for an additional key specifying the
command.  Normally the entire file is exported, but if there is an
active region that contains one outline tree, the first heading is used
as document title and the subtrees are exported.

`C-c C-e     (`org-export')'
     Dispatcher for export and publishing commands.  Displays a
     help-window listing the additional key(s) needed to launch an
     export or publishing command.  The prefix arg is passed through to
     the exporter.  A double prefix `C-u C-u' causes most commands to
     be executed in the background, in a separate Emacs process(1).  

`C-c C-e v     (`org-export-visible')'
     Like `C-c C-e', but only export the text that is currently visible
     (i.e. not hidden by outline visibility).  

`C-u C-u C-c C-e     (`org-export')'
     Call the exporter, but reverse the setting of
     `org-export-run-in-background', i.e. request background processing
     if not set, or force processing in the current Emacs process if
     set.

   ---------- Footnotes ----------

   (1) To make this behavior the default, customize the variable
`org-export-run-in-background'.


File: org,  Node: ASCII/Latin-1/UTF-8 export,  Next: HTML export,  Prev: The export dispatcher,  Up: Exporting

12.4 ASCII/Latin-1/UTF-8 export
===============================

ASCII export produces a simple and very readable version of an Org mode
file, containing only plain ASCII.  Latin-1 and UTF-8 export augment
the file with special characters and symbols available in these
encodings.

`C-c C-e a     (`org-export-as-ascii')'
     Export as ASCII file.  For an Org file, `myfile.org', the ASCII
     file will be `myfile.txt'.  The file will be overwritten without
     warning.  If there is an active region(1), only the region will be
     exported.  If the selected region is a single tree(2), the tree
     head will become the document title.  If the tree head entry has
     or inherits an `EXPORT_FILE_NAME' property, that name will be used
     for the export.  

`C-c C-e A     (`org-export-as-ascii-to-buffer')'
     Export to a temporary buffer.  Do not create a file.  

`C-c C-e n     (`org-export-as-latin1')'
`C-c C-e N     (`org-export-as-latin1-to-buffer')'
     Like the above commands, but use Latin-1 encoding.  

`C-c C-e u     (`org-export-as-utf8')'
`C-c C-e U     (`org-export-as-utf8-to-buffer')'
     Like the above commands, but use UTF-8 encoding.

`C-c C-e v a/n/u'
     Export only the visible part of the document.

   In the exported version, the first 3 outline levels will become
headlines, defining a general document structure.  Additional levels
will be exported as itemized lists.  If you want that transition to
occur at a different level, specify it with a prefix argument.  For
example,

     C-1 C-c C-e a

creates only top level headlines and does the rest as items.  When
headlines are converted to items, the indentation of the text following
the headline is changed to fit nicely under the item.  This is done with
the assumption that the first body line indicates the base indentation
of the body text.  Any indentation larger than this is adjusted to
preserve the layout relative to the first line.  Should there be lines
with less indentation than the first, these are left alone.

   Links will be exported in a footnote-like style, with the
descriptive part in the text and the link in a note before the next
heading.  See the variable `org-export-ascii-links-to-notes' for
details and other options.

   ---------- Footnotes ----------

   (1) This requires `transient-mark-mode' be turned on.

   (2) To select the current subtree, use `C-c @'.


File: org,  Node: HTML export,  Next: LaTeX and PDF export,  Prev: ASCII/Latin-1/UTF-8 export,  Up: Exporting

12.5 HTML export
================

Org mode contains an HTML (XHTML 1.0 strict) exporter with extensive
HTML formatting, in ways similar to John Gruber's _markdown_ language,
but with additional support for tables.

* Menu:

* HTML Export commands::        How to invoke HTML export
* HTML preamble and postamble::  How to insert a preamble and a postamble
* Quoting HTML tags::           Using direct HTML in Org mode
* Links in HTML export::        How links will be interpreted and formatted
* Tables in HTML export::       How to modify the formatting of tables
* Images in HTML export::       How to insert figures into HTML output
* Math formatting in HTML export::  Beautiful math also on the web
* Text areas in HTML export::   An alternative way to show an example
* CSS support::                 Changing the appearance of the output
* JavaScript support::          Info and Folding in a web browser


File: org,  Node: HTML Export commands,  Next: HTML preamble and postamble,  Prev: HTML export,  Up: HTML export

12.5.1 HTML export commands
---------------------------

`C-c C-e h     (`org-export-as-html')'
     Export as HTML file.  For an Org file `myfile.org', the HTML file
     will be `myfile.html'.  The file will be overwritten without
     warning.  If there is an active region(1), only the region will be
     exported.  If the selected region is a single tree(2), the tree
     head will become the document title.  If the tree head entry has,
     or inherits, an `EXPORT_FILE_NAME' property, that name will be
     used for the export.  

`C-c C-e b     (`org-export-as-html-and-open')'
     Export as HTML file and immediately open it with a browser.  

`C-c C-e H     (`org-export-as-html-to-buffer')'
     Export to a temporary buffer.  Do not create a file.  

`C-c C-e R     (`org-export-region-as-html')'
     Export the active region to a temporary buffer.  With a prefix
     argument, do not produce the file header and footer, but just the
     plain HTML section for the region.  This is good for cut-and-paste
     operations.

`C-c C-e v h/b/H/R'
     Export only the visible part of the document.

`M-x org-export-region-as-html'
     Convert the region to HTML under the assumption that it was Org
     mode syntax before.  This is a global command that can be invoked
     in any buffer.

`M-x org-replace-region-by-HTML'
     Replace the active region (assumed to be in Org mode syntax) by
     HTML code.

   In the exported version, the first 3 outline levels will become
headlines, defining a general document structure.  Additional levels
will be exported as itemized lists.  If you want that transition to
occur at a different level, specify it with a numeric prefix argument.
For example,

     C-2 C-c C-e b

creates two levels of headings and does the rest as items.

   ---------- Footnotes ----------

   (1) This requires `transient-mark-mode' be turned on.

   (2) To select the current subtree, use `C-c @'.


File: org,  Node: HTML preamble and postamble,  Next: Quoting HTML tags,  Prev: HTML Export commands,  Up: HTML export

12.5.2 HTML preamble and postamble
----------------------------------

The HTML exporter lets you define a preamble and a postamble.

   The default value for `org-export-html-preamble' is `t', which means
that the preamble is inserted depending on the relevant formatting
string in `org-export-html-preamble-format'.

   Setting `org-export-html-preamble' to a string will override the
default formatting string.  Setting it to a function, will insert the
output of the function, which must be a string; such a function takes
no argument but you can check against the value of `opt-plist', which
contains the list of publishing properties for the current file.
Setting to `nil' will not insert any preamble.

   The default value for `org-export-html-postamble' is `'auto', which
means that the HTML exporter will look for the value of
`org-export-author-info', `org-export-email-info',
`org-export-creator-info' and `org-export-time-stamp-file',
`org-export-html-validation-link' and build the postamble from these
values.  Setting `org-export-html-postamble' to `t' will insert the
postamble from the relevant formatting string found in
`org-export-html-postamble-format'.  Setting it to `nil' will not
insert any postamble.


File: org,  Node: Quoting HTML tags,  Next: Links in HTML export,  Prev: HTML preamble and postamble,  Up: HTML export

12.5.3 Quoting HTML tags
------------------------

Plain `<' and `>' are always transformed to `&lt;' and `&gt;' in HTML
export.  If you want to include simple HTML tags which should be
interpreted as such, mark them with `@' as in `@<b>bold text@</b>'.
Note that this really works only for simple tags.  For more extensive
HTML that should be copied verbatim to the exported file use either

     #+HTML: Literal HTML code for export

or 

     #+BEGIN_HTML
     All lines between these markers are exported literally
     #+END_HTML


File: org,  Node: Links in HTML export,  Next: Tables in HTML export,  Prev: Quoting HTML tags,  Up: HTML export

12.5.4 Links in HTML export
---------------------------

Internal links (*note Internal links::) will continue to work in HTML.
This includes automatic links created by radio targets (*note Radio
targets::).  Links to external files will still work if the target file
is on the same relative path as the published Org file.  Links to other
`.org' files will be translated into HTML links under the assumption
that an HTML version also exists of the linked file, at the same
relative path.  `id:' links can then be used to jump to specific
entries across files.  For information related to linking files while
publishing them to a publishing directory see *note Publishing links::.

   If you want to specify attributes for links, you can do so using a
special `#+ATTR_HTML' line to define attributes that will be added to
the `<a>' or `<img>' tags.  Here is an example that sets `title' and
`style' attributes for a link:

     #+ATTR_HTML: title="The Org mode homepage" style="color:red;"
     [[http://orgmode.org]]


File: org,  Node: Tables in HTML export,  Next: Images in HTML export,  Prev: Links in HTML export,  Up: HTML export

12.5.5 Tables
-------------

Org mode tables are exported to HTML using the table tag defined in
`org-export-html-table-tag'.  The default setting makes tables without
cell borders and frame.  If you would like to change this for individual
tables, place something like the following before the table:

     #+CAPTION: This is a table with lines around and between cells
     #+ATTR_HTML: border="2" rules="all" frame="border"


File: org,  Node: Images in HTML export,  Next: Math formatting in HTML export,  Prev: Tables in HTML export,  Up: HTML export

12.5.6 Images in HTML export
----------------------------

HTML export can inline images given as links in the Org file, and it
can make an image the clickable part of a link.  By default(1), images
are inlined if a link does not have a description.  So
`[[file:myimg.jpg]]' will be inlined, while `[[file:myimg.jpg][the
image]]' will just produce a link `the image' that points to the image.
If the description part itself is a `file:' link or a `http:' URL
pointing to an image, this image will be inlined and activated so that
clicking on the image will activate the link.  For example, to include
a thumbnail that will link to a high resolution version of the image,
you could use:

     [[file:highres.jpg][file:thumb.jpg]]

   If you need to add attributes to an inlined image, use a
`#+ATTR_HTML'.  In the example below we specify the `alt' and `title'
attributes to support text viewers and accessibility, and align it to
the right.

     #+CAPTION: A black cat stalking a spider
     #+ATTR_HTML: alt="cat/spider image" title="Action!" align="right"
     [[./img/a.jpg]]

You could use `http' addresses just as well.

   ---------- Footnotes ----------

   (1) But see the variable `org-export-html-inline-images'.


File: org,  Node: Math formatting in HTML export,  Next: Text areas in HTML export,  Prev: Images in HTML export,  Up: HTML export

12.5.7 Math formatting in HTML export
-------------------------------------

LaTeX math snippets (*note LaTeX fragments::) can be displayed in two
different ways on HTML pages.  The default is to use the MathJax system
(http://www.mathjax.org) which should work out of the box with Org mode
installation because `http://orgmode.org' serves `MathJax' for Org mode
users for small applications and for testing purposes.  If you plan to
use this regularly or on pages with significant page views, you should
install(1) MathJax on your own server in order to limit the load of our
server.  To configure `MathJax', use the variable
`org-export-html-mathjax-options' or insert something like the
following into the buffer:

     #+MATHJAX: align:"left" mathml:t path:"/MathJax/MathJax.js"

See the docstring of the variable `org-export-html-mathjax-options' for
the meaning of the parameters in this line.

   If you prefer, you can also request that LaTeX fragments are
processed into small images that will be inserted into the browser
page.  Before the availability of MathJax, this was the default method
for Org files.  This method requires that the `dvipng' program is
available on your system.  You can still get this processing with

     #+OPTIONS: LaTeX:dvipng

   ---------- Footnotes ----------

   (1) Installation instructions can be found on the MathJax website,
see `http://www.mathjax.org/resources/docs/?installation.html'.


File: org,  Node: Text areas in HTML export,  Next: CSS support,  Prev: Math formatting in HTML export,  Up: HTML export

12.5.8 Text areas in HTML export
--------------------------------

An alternative way to publish literal code examples in HTML is to use
text areas, where the example can even be edited before pasting it into
an application.  It is triggered by a `-t' switch at an `example' or
`src' block.  Using this switch disables any options for syntax and
label highlighting, and line numbering, which may be present.  You may
also use `-h' and `-w' switches to specify the height and width of the
text area, which default to the number of lines in the example, and 80,
respectively.  For example

     #+BEGIN_EXAMPLE -t -w 40
       (defun org-xor (a b)
          "Exclusive or."
          (if a (not b) b))
     #+END_EXAMPLE


File: org,  Node: CSS support,  Next: JavaScript support,  Prev: Text areas in HTML export,  Up: HTML export

12.5.9 CSS support
------------------

You can also give style information for the exported file.  The HTML
exporter assigns the following special CSS classes(1) to appropriate
parts of the document--your style specifications may change these, in
addition to any of the standard classes like for headlines, tables, etc.
     p.author            author information, including email
     p.date              publishing date
     p.creator           creator info, about org mode version
     .title              document title
     .todo               TODO keywords, all not-done states
     .done               the DONE keywords, all states that count as done
     .WAITING            each TODO keyword also uses a class named after itself
     .timestamp          timestamp
     .timestamp-kwd      keyword associated with a timestamp, like SCHEDULED
     .timestamp-wrapper  span around keyword plus timestamp
     .tag                tag in a headline
     ._HOME              each tag uses itself as a class, "@" replaced by "_"
     .target             target for links
     .linenr             the line number in a code example
     .code-highlighted   for highlighting referenced code lines
     div.outline-N       div for outline level N (headline plus text))
     div.outline-text-N  extra div for text at outline level N
     .section-number-N   section number in headlines, different for each level
     div.figure          how to format an inlined image
     pre.src             formatted source code
     pre.example         normal example
     p.verse             verse paragraph
     div.footnotes       footnote section headline
     p.footnote          footnote definition paragraph, containing a footnote
     .footref            a footnote reference number (always a <sup>)
     .footnum            footnote number in footnote definition (always <sup>)

   Each exported file contains a compact default style that defines
these classes in a basic way(2).  You may overwrite these settings, or
add to them by using the variables `org-export-html-style' (for
Org-wide settings) and `org-export-html-style-extra' (for more
fine-grained settings, like file-local settings).  To set the latter
variable individually for each file, you can use

     #+STYLE: <link rel="stylesheet" type="text/css" href="stylesheet.css" />

For longer style definitions, you can use several such lines.  You
could also directly write a `<style>' `</style>' section in this way,
without referring to an external file.

   In order to add styles to a subtree, use the `:HTML_CONTAINER_CLASS:'
property to assign a class to the tree.  In order to specify CSS styles
for a particular headline, you can use the id specified in a
`:CUSTOM_ID:' property.

   ---------- Footnotes ----------

   (1) If the classes on TODO keywords and tags lead to conflicts, use
the variables `org-export-html-todo-kwd-class-prefix' and
`org-export-html-tag-class-prefix' to make them unique.

   (2) This style is defined in the constant
`org-export-html-style-default', which you should not modify.  To turn
inclusion of these defaults off, customize
`org-export-html-style-include-default'


File: org,  Node: JavaScript support,  Prev: CSS support,  Up: HTML export

12.5.10 JavaScript supported display of web pages
-------------------------------------------------

Sebastian Rose has written a JavaScript program especially designed to
enhance the web viewing experience of HTML files created with Org.  This
program allows you to view large files in two different ways.  The
first one is an _Info_-like mode where each section is displayed
separately and navigation can be done with the `n' and `p' keys (and
some other keys as well, press `?' for an overview of the available
keys).  The second view type is a _folding_ view much like Org provides
inside Emacs.  The script is available at
`http://orgmode.org/org-info.js' and you can find the documentation for
it at `http://orgmode.org/worg/code/org-info-js/'.  We host the script
at our site, but if you use it a lot, you might not want to be
dependent on `orgmode.org' and prefer to install a local copy on your
own web server.

   To use the script, you need to make sure that the `org-jsinfo.el'
module gets loaded.  It should be loaded by default, but you can try
`M-x customize-variable <RET> org-modules <RET>' to convince yourself
that this is indeed the case.  All it then takes to make use of the
program is adding a single line to the Org file:

     #+INFOJS_OPT: view:info toc:nil

If this line is found, the HTML header will automatically contain the
code needed to invoke the script.  Using the line above, you can set
the following viewing options:

     path:    The path to the script.  The default is to grab the script from
              `http://orgmode.org/org-info.js', but you might want to have
              a local copy and use a path like `../scripts/org-info.js'.
     view:    Initial view when website is first shown.  Possible values are:
              info      Info-like interface with one section per page.
              overview  Folding interface, initially showing only top-level.
              content   Folding interface, starting with all headlines visible.
              showall   Folding interface, all headlines and text visible.
     sdepth:  Maximum headline level that will still become an independent
              section for info and folding modes.  The default is taken from
              `org-export-headline-levels' (= the `H' switch in `#+OPTIONS').
              If this is smaller than in `org-export-headline-levels', each
              info/folding section can still contain child headlines.
     toc:     Should the table of contents _initially_ be visible?
              Even when `nil', you can always get to the "toc" with `i'.
     tdepth:  The depth of the table of contents.  The defaults are taken from
              the variables `org-export-headline-levels' and `org-export-with-toc'.
     ftoc:    Does the CSS of the page specify a fixed position for the "toc"?
              If yes, the toc will never be displayed as a section.
     ltoc:    Should there be short contents (children) in each section?
              Make this `above' if the section should be above initial text.
     mouse:   Headings are highlighted when the mouse is over them.  Should be
              `underline' (default) or a background color like `#cccccc'.
     buttons: Should view-toggle buttons be everywhere?  When `nil' (the
              default), only one such button will be present.
   You can choose default values for these options by customizing the
variable `org-infojs-options'.  If you always want to apply the script
to your pages, configure the variable `org-export-html-use-infojs'.


File: org,  Node: LaTeX and PDF export,  Next: DocBook export,  Prev: HTML export,  Up: Exporting

12.6 LaTeX and PDF export
=========================

Org mode contains a LaTeX exporter written by Bastien Guerry.  With
further processing(1), this backend is also used to produce PDF output.
Since the LaTeX output uses `hyperref' to implement links and cross
references, the PDF output file will be fully linked.  Beware of the
fact that your `org' file has to be properly structured in order to be
correctly exported: respect the hierarchy of sections.

* Menu:

* LaTeX/PDF export commands::
* Header and sectioning::       Setting up the export file structure
* Quoting LaTeX code::       Incorporating literal LaTeX code
* Tables in LaTeX export::   Options for exporting tables to LaTeX
* Images in LaTeX export::   How to insert figures into LaTeX output
* Beamer class export::         Turning the file into a presentation

   ---------- Footnotes ----------

   (1) The default LaTeX output is designed for processing with
`pdftex' or LaTeX.  It includes packages that are not compatible with
`xetex' and possibly `luatex'.  See the variables
`org-export-latex-default-packages-alist' and
`org-export-latex-packages-alist'.


File: org,  Node: LaTeX/PDF export commands,  Next: Header and sectioning,  Prev: LaTeX and PDF export,  Up: LaTeX and PDF export

12.6.1 LaTeX export commands
----------------------------

`C-c C-e l     (`org-export-as-latex')'
     Export as LaTeX file.  For an Org file `myfile.org', the LaTeX
     file will be `myfile.tex'.  The file will be overwritten without
     warning.  If there is an active region(1), only the region will be
     exported.  If the selected region is a single tree(2), the tree
     head will become the document title.  If the tree head entry has
     or inherits an `EXPORT_FILE_NAME' property, that name will be used
     for the export.  

`C-c C-e L     (`org-export-as-latex-to-buffer')'
     Export to a temporary buffer.  Do not create a file.

`C-c C-e v l/L'
     Export only the visible part of the document.

`M-x org-export-region-as-latex'
     Convert the region to LaTeX under the assumption that it was Org
     mode syntax before.  This is a global command that can be invoked
     in any buffer.

`M-x org-replace-region-by-latex'
     Replace the active region (assumed to be in Org mode syntax) by
     LaTeX code.  

`C-c C-e p     (`org-export-as-pdf')'
     Export as LaTeX and then process to PDF.  

`C-c C-e d     (`org-export-as-pdf-and-open')'
     Export as LaTeX and then process to PDF, then open the resulting
     PDF file.

   In the exported version, the first 3 outline levels will become
headlines, defining a general document structure.  Additional levels
will be exported as description lists.  The exporter can ignore them or
convert them to a custom string depending on `org-latex-low-levels'.

   If you want that transition to occur at a different level, specify it
with a numeric prefix argument.  For example,

     C-2 C-c C-e l

creates two levels of headings and does the rest as items.

   ---------- Footnotes ----------

   (1) This requires `transient-mark-mode' be turned on.

   (2) To select the current subtree, use `C-c @'.


File: org,  Node: Header and sectioning,  Next: Quoting LaTeX code,  Prev: LaTeX/PDF export commands,  Up: LaTeX and PDF export

12.6.2 Header and sectioning structure
--------------------------------------

By default, the LaTeX output uses the class `article'.

   You can change this globally by setting a different value for
`org-export-latex-default-class' or locally by adding an option like
`#+LaTeX_CLASS: myclass' in your file, or with a `:LaTeX_CLASS:'
property that applies when exporting a region containing only this
(sub)tree.  The class must be listed in `org-export-latex-classes'.
This variable defines a header template for each class(1), and allows
you to define the sectioning structure for each class.  You can also
define your own classes there.  `#+LaTeX_CLASS_OPTIONS' or a
`LaTeX_CLASS_OPTIONS' property can specify the options for the
`\documentclass' macro.  You can also use `#+LATEX_HEADER:
\usepackage{xyz}' to add lines to the header.  See the docstring of
`org-export-latex-classes' for more information.

   ---------- Footnotes ----------

   (1) Into which the values of
`org-export-latex-default-packages-alist' and
`org-export-latex-packages-alist' are spliced.


File: org,  Node: Quoting LaTeX code,  Next: Tables in LaTeX export,  Prev: Header and sectioning,  Up: LaTeX and PDF export

12.6.3 Quoting LaTeX code
-------------------------

Embedded LaTeX as described in *note Embedded LaTeX::, will be correctly
inserted into the LaTeX file.  This includes simple macros like
`\ref{LABEL}' to create a cross reference to a figure.  Furthermore,
you can add special code that should only be present in LaTeX export
with the following constructs:

     #+LaTeX: Literal LaTeX code for export

or 

     #+BEGIN_LaTeX
     All lines between these markers are exported literally
     #+END_LaTeX


File: org,  Node: Tables in LaTeX export,  Next: Images in LaTeX export,  Prev: Quoting LaTeX code,  Up: LaTeX and PDF export

12.6.4 Tables in LaTeX export
-----------------------------

For LaTeX export of a table, you can specify a label, a caption and
placement options (*note Images and tables::).  You can also use the
`ATTR_LaTeX' line to request a `longtable' environment for the table,
so that it may span several pages, or to change the default table
environment from `table' to `table*' or to change the default inner
tabular environment to `tabularx' or `tabulary'.  Finally, you can set
the alignment string, and (with `tabularx' or `tabulary') the width:

     #+CAPTION: A long table
     #+LABEL: tbl:long
     #+ATTR_LaTeX: longtable align=l|lp{3cm}r|l
     | ..... | ..... |
     | ..... | ..... |

   or to specify a multicolumn table with `tabulary'

     #+CAPTION: A wide table with tabulary
     #+LABEL: tbl:wide
     #+ATTR_LaTeX: table* tabulary width=\textwidth
     | ..... | ..... |
     | ..... | ..... |


File: org,  Node: Images in LaTeX export,  Next: Beamer class export,  Prev: Tables in LaTeX export,  Up: LaTeX and PDF export

12.6.5 Images in LaTeX export
-----------------------------

Images that are linked to without a description part in the link, like
`[[file:img.jpg]]' or `[[./img.jpg]]' will be inserted into the PDF
output file resulting from LaTeX processing.  Org will use an
`\includegraphics' macro to insert the image.  If you have specified a
caption and/or a label as described in *note Images and tables::, the
figure will be wrapped into a `figure' environment and thus become a
floating element.  You can use an `#+ATTR_LaTeX:' line to specify
various other options.  You can ask org to export an image as a float
without specifying a label or a caption by using the keyword `float' in
this line.  Various optional arguments to the `\includegraphics' macro
can also be specified in this fashion.  To modify the placement option
of the floating environment, add something like `placement=[h!]' to the
attributes.  It is to be noted this option can be used with tables as
well(1).  For example the `#+ATTR_LaTeX:' line below is exported as the
`figure' environment below it.

   If you would like to let text flow around the image, add the word
`wrap' to the `#+ATTR_LaTeX:' line, which will make the figure occupy
the left half of the page.  To fine-tune, the `placement' field will be
the set of additional arguments needed by the `wrapfigure' environment.
Note that if you change the size of the image, you need to use
compatible settings for `\includegraphics' and `wrapfigure'.

     #+CAPTION:    The black-body emission of the disk around HR 4049
     #+LABEL:      fig:SED-HR4049
     #+ATTR_LaTeX: width=5cm,angle=90
     [[./img/sed-hr4049.pdf]]

     #+ATTR_LaTeX: width=0.38\textwidth wrap placement={r}{0.4\textwidth}
     [[./img/hst.png]]

   If you wish to include an image which spans multiple columns in a
page, you can use the keyword `multicolumn' in the `#+ATTR_LaTeX' line.
This will export the image wrapped in a `figure*' environment.

   If you need references to a label created in this way, write
`\ref{fig:SED-HR4049}' just like in LaTeX.

   ---------- Footnotes ----------

   (1) One can also take advantage of this option to pass other,
unrelated options into the figure or table environment.  For an example
see the section "Exporting org files" in
`http://orgmode.org/worg/org-hacks.html'


File: org,  Node: Beamer class export,  Prev: Images in LaTeX export,  Up: LaTeX and PDF export

12.6.6 Beamer class export
--------------------------

The LaTeX class `beamer' allows production of high quality presentations
using LaTeX and pdf processing.  Org mode has special support for
turning an Org mode file or tree into a `beamer' presentation.

   When the LaTeX class for the current buffer (as set with
`#+LaTeX_CLASS: beamer') or subtree (set with a `LaTeX_CLASS' property)
is `beamer', a special export mode will turn the file or tree into a
beamer presentation.  Any tree with not-too-deep level nesting should
in principle be exportable as a beamer presentation.  By default, the
top-level entries (or the first level below the selected subtree
heading) will be turned into frames, and the outline structure below
this level will become itemize lists.  You can also configure the
variable `org-beamer-frame-level' to a different level--then the
hierarchy above frames will produce the sectioning structure of the
presentation.

   A template for useful in-buffer settings or properties can be
inserted into the buffer with `M-x org-insert-beamer-options-template'.
Among other things, this will install a column view format which is
very handy for editing special properties used by beamer.

   You can influence the structure of the presentation using the
following properties:

`BEAMER_env'
     The environment that should be used to format this entry.  Valid
     environments are defined in the constant
     `org-beamer-environments-default', and you can define more in
     `org-beamer-environments-extra'.  If this property is set, the
     entry will also get a `:B_environment:' tag to make this visible.
     This tag has no semantic meaning, it is only a visual aid.

`BEAMER_envargs'
     The beamer-special arguments that should be used for the
     environment, like `[t]' or `[<+->]' of `<2-3>'.  If the
     `BEAMER_col' property is also set, something like `C[t]' can be
     added here as well to set an options argument for the implied
     `columns' environment.  `c[t]' or `c<2->' will set an options for
     the implied `column' environment.

`BEAMER_col'
     The width of a column that should start with this entry.  If this
     property is set, the entry will also get a `:BMCOL:' property to
     make this visible.  Also this tag is only a visual aid.  When this
     is a plain number, it will be interpreted as a fraction of
     `\textwidth'.  Otherwise it will be assumed that you have
     specified the units, like `3cm'.  The first such property in a
     frame will start a `columns' environment to surround the columns.
     This environment is closed when an entry has a `BEAMER_col'
     property with value 0 or 1, or automatically at the end of the
     frame.

`BEAMER_extra'
     Additional commands that should be inserted after the environment
     has been opened.  For example, when creating a frame, this can be
     used to specify transitions.

   Frames will automatically receive a `fragile' option if they contain
source code that uses the verbatim environment.  Special `beamer'
specific code can be inserted using `#+BEAMER:' and
`#+BEGIN_beamer...#+end_beamer' constructs, similar to other export
backends, but with the difference that `#+LaTeX:' stuff will be included
in the presentation as well.

   Outline nodes with `BEAMER_env' property value `note' or `noteNH'
will be formatted as beamer notes, i,e, they will be wrapped into
`\note{...}'.  The former will include the heading as part of the note
text, the latter will ignore the heading of that node.  To simplify note
generation, it is actually enough to mark the note with a _tag_ (either
`:B_note:' or `:B_noteNH:') instead of creating the `BEAMER_env'
property.

   You can turn on a special minor mode `org-beamer-mode' for editing
support with

     #+STARTUP: beamer

`C-c C-b     (`org-beamer-select-environment')'
     In `org-beamer-mode', this key offers fast selection of a beamer
     environment or the `BEAMER_col' property.

   Column view provides a great way to set the environment of a node
and other important parameters.  Make sure you are using a COLUMN
format that is geared toward this special purpose.  The command `M-x
org-insert-beamer-options-template' defines such a format.

   Here is a simple example Org document that is intended for beamer
export.

     #+LaTeX_CLASS: beamer
     #+TITLE: Example Presentation
     #+AUTHOR: Carsten Dominik
     #+LaTeX_CLASS_OPTIONS: [presentation]
     #+BEAMER_FRAME_LEVEL: 2
     #+BEAMER_HEADER_EXTRA: \usetheme{Madrid}\usecolortheme{default}
     #+COLUMNS: %35ITEM %10BEAMER_env(Env) %10BEAMER_envargs(Args) %4BEAMER_col(Col) %8BEAMER_extra(Ex)

     * This is the first structural section

     ** Frame 1 \\ with a subtitle
     *** Thanks to Eric Fraga                                      :BMCOL:B_block:
         :PROPERTIES:
         :BEAMER_env: block
         :BEAMER_envargs: C[t]
         :BEAMER_col: 0.5
         :END:
         for the first viable beamer setup in Org
     *** Thanks to everyone else                                   :BMCOL:B_block:
         :PROPERTIES:
         :BEAMER_col: 0.5
         :BEAMER_env: block
         :BEAMER_envargs: <2->
         :END:
         for contributing to the discussion
     **** This will be formatted as a beamer note                  :B_note:
     ** Frame 2 \\ where we will not use columns
     *** Request                                                   :B_block:
         Please test this stuff!
         :PROPERTIES:
         :BEAMER_env: block
         :END:

   For more information, see the documentation on Worg.


File: org,  Node: DocBook export,  Next: OpenDocument Text export,  Prev: LaTeX and PDF export,  Up: Exporting

12.7 DocBook export
===================

Org contains a DocBook exporter written by Baoqiu Cui.  Once an Org
file is exported to DocBook format, it can be further processed to
produce other formats, including PDF, HTML, man pages, etc., using many
available DocBook tools and stylesheets.

   Currently DocBook exporter only supports DocBook V5.0.

* Menu:

* DocBook export commands::     How to invoke DocBook export
* Quoting DocBook code::        Incorporating DocBook code in Org files
* Recursive sections::          Recursive sections in DocBook
* Tables in DocBook export::    Tables are exported as HTML tables
* Images in DocBook export::    How to insert figures into DocBook output
* Special characters::          How to handle special characters


File: org,  Node: DocBook export commands,  Next: Quoting DocBook code,  Prev: DocBook export,  Up: DocBook export

12.7.1 DocBook export commands
------------------------------

`C-c C-e D     (`org-export-as-docbook')'
     Export as DocBook file.  For an Org file, `myfile.org', the
     DocBook XML file will be `myfile.xml'.  The file will be
     overwritten without warning.  If there is an active region(1),
     only the region will be exported.  If the selected region is a
     single tree(2), the tree head will become the document title.  If
     the tree head entry has, or inherits, an `EXPORT_FILE_NAME'
     property, that name will be used for the export.  

`C-c C-e V     (`org-export-as-docbook-pdf-and-open')'
     Export as DocBook file, process to PDF, then open the resulting
     PDF file.

     Note that, in order to produce PDF output based on exported
     DocBook file, you need to have XSLT processor and XSL-FO processor
     software installed on your system.  Check variables
     `org-export-docbook-xslt-proc-command' and
     `org-export-docbook-xsl-fo-proc-command'.

     The stylesheet argument `%s' in variable
     `org-export-docbook-xslt-proc-command' is replaced by the value of
     variable `org-export-docbook-xslt-stylesheet', which needs to be
     set by the user.  You can also overrule this global setting on a
     per-file basis by adding an in-buffer setting `#+XSLT:' to the Org
     file.

`C-c C-e v D'
     Export only the visible part of the document.

   ---------- Footnotes ----------

   (1) This requires `transient-mark-mode' to be turned on

   (2) To select the current subtree, use `C-c @'.


File: org,  Node: Quoting DocBook code,  Next: Recursive sections,  Prev: DocBook export commands,  Up: DocBook export

12.7.2 Quoting DocBook code
---------------------------

You can quote DocBook code in Org files and copy it verbatim into
exported DocBook file with the following constructs:

     #+DOCBOOK: Literal DocBook code for export

or 

     #+BEGIN_DOCBOOK
     All lines between these markers are exported by DocBook exporter
     literally.
     #+END_DOCBOOK

   For example, you can use the following lines to include a DocBook
warning admonition.  As to what this warning says, you should pay
attention to the document context when quoting DocBook code in Org
files.  You may make exported DocBook XML files invalid by not quoting
DocBook code correctly.

     #+BEGIN_DOCBOOK
     <warning>
       <para>You should know what you are doing when quoting DocBook XML code
       in your Org file.  Invalid DocBook XML may be generated by
       DocBook exporter if you are not careful!</para>
     </warning>
     #+END_DOCBOOK


File: org,  Node: Recursive sections,  Next: Tables in DocBook export,  Prev: Quoting DocBook code,  Up: DocBook export

12.7.3 Recursive sections
-------------------------

DocBook exporter exports Org files as articles using the `article'
element in DocBook.  Recursive sections, i.e. `section' elements, are
used in exported articles.  Top level headlines in Org files are
exported as top level sections, and lower level headlines are exported
as nested sections.  The entire structure of Org files will be exported
completely, no matter how many nested levels of headlines there are.

   Using recursive sections makes it easy to port and reuse exported
DocBook code in other DocBook document types like `book' or `set'.


File: org,  Node: Tables in DocBook export,  Next: Images in DocBook export,  Prev: Recursive sections,  Up: DocBook export

12.7.4 Tables in DocBook export
-------------------------------

Tables in Org files are exported as HTML tables, which have been
supported since DocBook V4.3.

   If a table does not have a caption, an informal table is generated
using the `informaltable' element; otherwise, a formal table will be
generated using the `table' element.


File: org,  Node: Images in DocBook export,  Next: Special characters,  Prev: Tables in DocBook export,  Up: DocBook export

12.7.5 Images in DocBook export
-------------------------------

Images that are linked to without a description part in the link, like
`[[file:img.jpg]]' or `[[./img.jpg]]', will be exported to DocBook
using `mediaobject' elements.  Each `mediaobject' element contains an
`imageobject' that wraps an `imagedata' element.  If you have specified
a caption for an image as described in *note Images and tables::, a
`caption' element will be added in `mediaobject'.  If a label is also
specified, it will be exported as an `xml:id' attribute of the
`mediaobject' element.

   Image attributes supported by the `imagedata' element, like `align'
or `width', can be specified in two ways: you can either customize
variable `org-export-docbook-default-image-attributes' or use the
`#+ATTR_DOCBOOK:' line.  Attributes specified in variable
`org-export-docbook-default-image-attributes' are applied to all inline
images in the Org file to be exported (unless they are overridden by
image attributes specified in `#+ATTR_DOCBOOK:' lines).

   The `#+ATTR_DOCBOOK:' line can be used to specify additional image
attributes or override default image attributes for individual images.
If the same attribute appears in both the `#+ATTR_DOCBOOK:' line and
variable `org-export-docbook-default-image-attributes', the former
takes precedence.  Here is an example about how image attributes can be
set:

     #+CAPTION:    The logo of Org mode
     #+LABEL:      unicorn-svg
     #+ATTR_DOCBOOK: scalefit="1" width="100%" depth="100%"
     [[./img/org-mode-unicorn.svg]]

   By default, DocBook exporter recognizes the following image file
types: `jpeg', `jpg', `png', `gif', and `svg'.  You can customize
variable `org-export-docbook-inline-image-extensions' to add more types
to this list as long as DocBook supports them.


File: org,  Node: Special characters,  Prev: Images in DocBook export,  Up: DocBook export

12.7.6 Special characters in DocBook export
-------------------------------------------

Special characters that are written in TeX-like syntax, such as
`\alpha', `\Gamma', and `\Zeta', are supported by DocBook exporter.
These characters are rewritten to XML entities, like `&alpha;',
`&Gamma;', and `&Zeta;', based on the list saved in variable
`org-entities'.  As long as the generated DocBook file includes the
corresponding entities, these special characters are recognized.

   You can customize variable `org-export-docbook-doctype' to include
the entities you need.  For example, you can set variable
`org-export-docbook-doctype' to the following value to recognize all
special characters included in XHTML entities:

     "<!DOCTYPE article [
     <!ENTITY % xhtml1-symbol PUBLIC
     \"-//W3C//ENTITIES Symbol for HTML//EN//XML\"
     \"http://www.w3.org/2003/entities/2007/xhtml1-symbol.ent\"
     >
     %xhtml1-symbol;
     ]>
     "


File: org,  Node: OpenDocument Text export,  Next: TaskJuggler export,  Prev: DocBook export,  Up: Exporting

12.8 OpenDocument Text export
=============================

Orgmode(1) supports export to OpenDocument Text (ODT) format using the
`org-odt.el' module.  Documents created by this exporter use the
`OpenDocument-v1.2 specification'(2) and are compatible with
LibreOffice 3.4.

* Menu:

* Pre-requisites for ODT export::  What packages ODT exporter relies on
* ODT export commands::         How to invoke ODT export
* Extending ODT export::        How to produce `doc', `pdf' files
* Applying custom styles::      How to apply custom styles to the output
* Links in ODT export::         How links will be interpreted and formatted
* Tables in ODT export::        How Tables are exported
* Images in ODT export::        How to insert images
* Math formatting in ODT export::  How LaTeX fragments are formatted
* Labels and captions in ODT export::  How captions are rendered
* Literal examples in ODT export::  How source and example blocks are formatted
* Advanced topics in ODT export::  Read this if you are a power user

   ---------- Footnotes ----------

   (1) Versions 7.8 or later

   (2) Open Document Format for Office Applications (OpenDocument)
Version 1.2
(http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html)


File: org,  Node: Pre-requisites for ODT export,  Next: ODT export commands,  Prev: OpenDocument Text export,  Up: OpenDocument Text export

12.8.1 Pre-requisites for ODT export
------------------------------------

The ODT exporter relies on the `zip' program to create the final
output.  Check the availability of this program before proceeding
further.


File: org,  Node: ODT export commands,  Next: Extending ODT export,  Prev: Pre-requisites for ODT export,  Up: OpenDocument Text export

12.8.2 ODT export commands
--------------------------

Exporting to ODT
................

`C-c C-e o     (`org-export-as-odt')'
     Export as OpenDocument Text file.

     If `org-export-odt-preferred-output-format' is specified,
     automatically convert the exported file to that format.  *Note
     Automatically exporting to other formats:
     x-export-to-other-formats.

     For an Org file `myfile.org', the ODT file will be `myfile.odt'.
     The file will be overwritten without warning.  If there is an
     active region,(1) only the region will be exported.  If the
     selected region is a single tree,(2) the tree head will become the
     document title.  If the tree head entry has, or inherits, an
     `EXPORT_FILE_NAME' property, that name will be used for the export.

`C-c C-e O     (`org-export-as-odt-and-open')'
     Export as OpenDocument Text file and open the resulting file.

     If `org-export-odt-preferred-output-format' is specified, open the
     converted file instead.  *Note Automatically exporting to other
     formats: x-export-to-other-formats.

   ---------- Footnotes ----------

   (1) This requires `transient-mark-mode' to be turned on

   (2) To select the current subtree, use `C-c @'


File: org,  Node: Extending ODT export,  Next: Applying custom styles,  Prev: ODT export commands,  Up: OpenDocument Text export

12.8.3 Extending ODT export
---------------------------

The ODT exporter can interface with a variety of document converters
and supports popular converters out of the box.  As a result, you can
use it to export to formats like `doc' or convert a document from one
format (say `csv') to another format (say `ods' or `xls').

   If you have a working installation of LibreOffice, a document
converter is pre-configured for you and you can use it right away.  If
you would like to use `unoconv' as your preferred converter, customize
the variable `org-export-odt-convert-process' to point to `unoconv'.
You can also use your own favorite converter or tweak the default
settings of the `LibreOffice' and `unoconv' converters.  *Note
Configuring a document converter::.

12.8.3.1 Automatically exporting to other formats
.................................................

Very often, you will find yourself exporting to ODT format, only to
immediately save the exported document to other formats like `doc',
`docx', `rtf', `pdf' etc.  In such cases, you can specify your
preferred output format by customizing the variable
`org-export-odt-preferred-output-format'.  This way, the export commands
(*note Exporting to ODT: x-export-to-odt.) can be extended to export to
a format that is of immediate interest to you.

12.8.3.2 Converting between document formats
............................................

There are many document converters in the wild which support conversion
to and from various file formats, including, but not limited to the ODT
format.  LibreOffice converter, mentioned above, is one such converter.
Once a converter is configured, you can interact with it using the
following command.

`M-x org-export-odt-convert'
     Convert an existing document from one format to another.  With a
     prefix argument, also open the newly produced file.


File: org,  Node: Applying custom styles,  Next: Links in ODT export,  Prev: Extending ODT export,  Up: OpenDocument Text export

12.8.4 Applying custom styles
-----------------------------

The ODT exporter ships with a set of OpenDocument styles (*note Working
with OpenDocument style files::) that ensure a well-formatted output.
These factory styles, however, may not cater to your specific tastes.
To customize the output, you can either modify the above styles files
directly, or generate the required styles using an application like
LibreOffice.  The latter method is suitable for expert and non-expert
users alike, and is described here.

12.8.4.1 Applying custom styles - the easy way
..............................................

  1. Create a sample `example.org' file with the below settings and
     export it to ODT format.

          #+OPTIONS: H:10 num:t

  2. Open the above `example.odt' using LibreOffice.  Use the `Stylist'
     to locate the target styles - these typically have the `Org'
     prefix - and modify those to your taste.  Save the modified file
     either as an OpenDocument Text (`.odt') or OpenDocument Template
     (`.ott') file.

  3. Customize the variable `org-export-odt-styles-file' and point it
     to the newly created file.  For additional configuration options
     *note Overriding factory styles: x-overriding-factory-styles.

     If you would like to choose a style on a per-file basis, you can
     use the `#+ODT_STYLES_FILE' option.  A typical setting will look
     like

          #+ODT_STYLES_FILE: "/path/to/example.ott"

     or

          #+ODT_STYLES_FILE: ("/path/to/file.ott" ("styles.xml" "image/hdr.png"))


12.8.4.2 Using third-party styles and templates
...............................................

You can use third-party styles and templates for customizing your
output.  This will produce the desired output only if the template
provides all style names that the `ODT' exporter relies on.  Unless
this condition is met, the output is going to be less than
satisfactory.  So it is highly recommended that you only work with
templates that are directly derived from the factory settings.


File: org,  Node: Links in ODT export,  Next: Tables in ODT export,  Prev: Applying custom styles,  Up: OpenDocument Text export

12.8.5 Links in ODT export
--------------------------

ODT exporter creates native cross-references for internal links.  It
creates Internet-style links for all other links.

   A link with no description and destined to a regular (un-itemized)
outline heading is replaced with a cross-reference and section number
of the heading.

   A `\ref{label}'-style reference to an image, table etc. is replaced
with a cross-reference and sequence number of the labeled entity.
*Note Labels and captions in ODT export::.


File: org,  Node: Tables in ODT export,  Next: Images in ODT export,  Prev: Links in ODT export,  Up: OpenDocument Text export

12.8.6 Tables in ODT export
---------------------------

Export of native Org mode tables (*note Tables::) and simple `table.el'
tables is supported.  However, export of complex `table.el' tables -
tables that have column or row spans - is not supported.  Such tables
are stripped from the exported document.

   By default, a table is exported with top and bottom frames and with
rules separating row and column groups (*note Column groups::).
Furthermore, all tables are typeset to occupy the same width.  If the
table specifies alignment and relative width for its columns (*note
Column width and alignment::) then these are honored on export.(1)

   You can control the width of the table by specifying `:rel-width'
property using an `#+ATTR_ODT' line.

   For example, consider the following table which makes use of all the
rules mentioned above.

     #+ATTR_ODT: :rel-width 50
     | Area/Month    |   Jan |   Feb |   Mar |   Sum |
     |---------------+-------+-------+-------+-------|
     | /             |     < |       |       |     < |
     | <l13>         |  <r5> |  <r5> |  <r5> |  <r6> |
     | North America |     1 |    21 |   926 |   948 |
     | Middle East   |     6 |    75 |   844 |   925 |
     | Asia Pacific  |     9 |    27 |   790 |   826 |
     |---------------+-------+-------+-------+-------|
     | Sum           |    16 |   123 |  2560 |  2699 |

   On export, the table will occupy 50% of text area.  The columns will
be sized (roughly) in the ratio of 13:5:5:5:6.  The first column will
be left-aligned and rest of the columns will be right-aligned.  There
will be vertical rules after separating the header and last columns
from other columns.  There will be horizontal rules separating the
header and last rows from other rows.

   If you are not satisfied with the above formatting options, you can
create custom table styles and associate them with a table using the
`#+ATTR_ODT' line.  *Note Customizing tables in ODT export::.

   ---------- Footnotes ----------

   (1) The column widths are interpreted as weighted ratios with the
default weight being 1


File: org,  Node: Images in ODT export,  Next: Math formatting in ODT export,  Prev: Tables in ODT export,  Up: OpenDocument Text export

12.8.7 Images in ODT export
---------------------------

Embedding images
................

You can embed images within the exported document by providing a link
to the desired image file with no link description.  For example, to
embed `img.png' do either of the following:

     [[file:img.png]]

     [[./img.png]]

Embedding clickable images
..........................

You can create clickable images by providing a link whose description
is a link to an image file.  For example, to embed a image
`org-mode-unicorn.png' which when clicked jumps to `http://Orgmode.org'
website, do the following

     [[http://orgmode.org][./org-mode-unicorn.png]]

Sizing and scaling of embedded images
.....................................

You can control the size and scale of the embedded images using the
`#+ATTR_ODT' attribute.

   The exporter specifies the desired size of the image in the final
document in units of centimeters.  In order to scale the embedded
images, the exporter queries for pixel dimensions of the images using
one of a) ImageMagick's `identify' program or b) Emacs `create-image'
and `image-size' APIs.(1) The pixel dimensions are subsequently
converted in to units of centimeters using
`org-export-odt-pixels-per-inch'.  The default value of this variable is
set to `display-pixels-per-inch'.  You can tweak this variable to
achieve the best results.

   The examples below illustrate the various possibilities.

Explicitly size the image
     To embed `img.png' as a 10 cm x 10 cm image, do the following:

          #+ATTR_ODT: :width 10 :height 10
          [[./img.png]]

Scale the image
     To embed `img.png' at half its size, do the following:

          #+ATTR_ODT: :scale 0.5
          [[./img.png]]

Scale the image to a specific width
     To embed `img.png' with a width of 10 cm while retaining the
     original height:width ratio, do the following:

          #+ATTR_ODT: :width 10
          [[./img.png]]

Scale the image to a specific height
     To embed `img.png' with a height of 10 cm while retaining the
     original height:width ratio, do the following

          #+ATTR_ODT: :height 10
          [[./img.png]]

Anchoring of images
...................

You can control the manner in which an image is anchored by setting the
`:anchor' property of it's `#+ATTR_ODT' line.  You can specify one of
the the following three values for the `:anchor' property -
`"as-char"', `"paragraph"' and `"page"'.

   To create an image that is anchored to a page, do the following:
     #+ATTR_ODT: :anchor "page"
     [[./img.png]]

   ---------- Footnotes ----------

   (1) Use of `ImageMagick' is only desirable.  However, if you
routinely produce documents that have large images or you export your
Org files that has images using a Emacs batch script, then the use of
`ImageMagick' is mandatory.


File: org,  Node: Math formatting in ODT export,  Next: Labels and captions in ODT export,  Prev: Images in ODT export,  Up: OpenDocument Text export

12.8.8 Math formatting in ODT export
------------------------------------

The ODT exporter has special support for handling math.

* Menu:

* Working with LaTeX math snippets::  How to embed LaTeX math fragments
* Working with MathML or OpenDocument formula files::  How to embed equations in native format


File: org,  Node: Working with LaTeX math snippets,  Next: Working with MathML or OpenDocument formula files,  Prev: Math formatting in ODT export,  Up: Math formatting in ODT export

12.8.8.1 Working with LaTeX math snippets
.........................................

LaTeX math snippets (*note LaTeX fragments::) can be embedded in the ODT
document in one of the following ways:

  1. MathML

     This option is activated on a per-file basis with

          #+OPTIONS: LaTeX:t

     With this option, LaTeX fragments are first converted into MathML
     fragments using an external LaTeX-to-MathML converter program.  The
     resulting MathML fragments are then embedded as an OpenDocument
     Formula in the exported document.

     You can specify the LaTeX-to-MathML converter by customizing the
     variables `org-latex-to-mathml-convert-command' and
     `org-latex-to-mathml-jar-file'.

     If you prefer to use `MathToWeb'(1) as your converter, you can
     configure the above variables as shown below.

          (setq org-latex-to-mathml-convert-command
                "java -jar %j -unicode -force -df %o %I"
                org-latex-to-mathml-jar-file
                "/path/to/mathtoweb.jar")

     You can use the following commands to quickly verify the
     reliability of the LaTeX-to-MathML converter.

    `M-x org-export-as-odf'
          Convert a LaTeX math snippet to OpenDocument formula (`.odf')
          file.

    `M-x org-export-as-odf-and-open'
          Convert a LaTeX math snippet to OpenDocument formula (`.odf')
          file and open the formula file with the system-registered
          application.

  2. PNG images

     This option is activated on a per-file basis with

          #+OPTIONS: LaTeX:dvipng

     With this option, LaTeX fragments are processed into PNG images
     and the resulting images are embedded in the exported document.
     This method requires that the `dvipng' program be available on
     your system.

   ---------- Footnotes ----------

   (1) See MathToWeb
(http://www.mathtoweb.com/cgi-bin/mathtoweb_home.pl)


File: org,  Node: Working with MathML or OpenDocument formula files,  Prev: Working with LaTeX math snippets,  Up: Math formatting in ODT export

12.8.8.2 Working with MathML or OpenDocument formula files
..........................................................

For various reasons, you may find embedding LaTeX math snippets in an
ODT document less than reliable.  In that case, you can embed a math
equation by linking to its MathML (`.mml') source or its OpenDocument
formula (`.odf') file as shown below:

     [[./equation.mml]]

   or

     [[./equation.odf]]


File: org,  Node: Labels and captions in ODT export,  Next: Literal examples in ODT export,  Prev: Math formatting in ODT export,  Up: OpenDocument Text export

12.8.9 Labels and captions in ODT export
----------------------------------------

You can label and caption various category of objects - an inline
image, a table, a LaTeX fragment or a Math formula - using `#+LABEL' and
`#+CAPTION' lines.  *Note Images and tables::.  ODT exporter enumerates
each labeled or captioned object of a given category separately.  As a
result, each such object is assigned a sequence number based on order
of it's appearance in the Org file.

   In the exported document, a user-provided caption is augmented with
the category and sequence number.  Consider the following inline image
in an Org file.

     #+CAPTION: Bell curve
     #+LABEL:   fig:SED-HR4049
     [[./img/a.png]]

   It could be rendered as shown below in the exported document.

     Figure 2: Bell curve

   You can modify the category component of the caption by customizing
the variable `org-export-odt-category-strings'.  For example, to tag all
embedded images with the string `Illustration' (instead of the default
`Figure') use the following setting.

     (setq org-export-odt-category-strings
           '(("en" "Table" "Illustration" "Equation" "Equation")))

   With this, previous image will be captioned as below in the exported
document.

     Illustration 2: Bell curve


File: org,  Node: Literal examples in ODT export,  Next: Advanced topics in ODT export,  Prev: Labels and captions in ODT export,  Up: OpenDocument Text export

12.8.10 Literal examples in ODT export
--------------------------------------

Export of literal examples (*note Literal examples::) with full
fontification is supported.  Internally, the exporter relies on
`htmlfontify.el' to generate all style definitions needed for a fancy
listing.(1)  The auto-generated styles have `OrgSrc' as prefix and
inherit their color from the faces used by Emacs `font-lock' library
for the source language.

   If you prefer to use your own custom styles for fontification, you
can do so by customizing the variable
`org-export-odt-create-custom-styles-for-srcblocks'.

   You can turn off fontification of literal examples by customizing the
variable `org-export-odt-fontify-srcblocks'.

   ---------- Footnotes ----------

   (1) Your `htmlfontify.el' library must at least be at Emacs 24.1
levels for fontification to be turned on.


File: org,  Node: Advanced topics in ODT export,  Prev: Literal examples in ODT export,  Up: OpenDocument Text export

12.8.11 Advanced topics in ODT export
-------------------------------------

If you rely heavily on ODT export, you may want to exploit the full set
of features that the exporter offers.  This section describes features
that would be of interest to power users.

* Menu:

* Configuring a document converter::  How to register a document converter
* Working with OpenDocument style files::  Explore the internals
* Creating one-off styles::     How to produce custom highlighting etc
* Customizing tables in ODT export::  How to define and use Table templates
* Validating OpenDocument XML::  How to debug corrupt OpenDocument files


File: org,  Node: Configuring a document converter,  Next: Working with OpenDocument style files,  Prev: Advanced topics in ODT export,  Up: Advanced topics in ODT export

12.8.11.1 Configuring a document converter
..........................................

The ODT exporter can work with popular converters with little or no
extra configuration from your side. *Note Extending ODT export::.  If
you are using a converter that is not supported by default or if you
would like to tweak the default converter settings, proceed as below.

  1. Register the converter

     Name your converter and add it to the list of known converters by
     customizing the variable `org-export-odt-convert-processes'.  Also
     specify how the converter can be invoked via command-line to
     effect the conversion.

  2. Configure its capabilities

     Specify the set of formats the converter can handle by customizing
     the variable `org-export-odt-convert-capabilities'.  Use the
     default value for this variable as a guide for configuring your
     converter.  As suggested by the default setting, you can specify
     the full set of formats supported by the converter and not limit
     yourself to specifying formats that are related to just the
     OpenDocument Text format.

  3. Choose the converter

     Select the newly added converter as the preferred one by
     customizing the variable `org-export-odt-convert-process'.


File: org,  Node: Working with OpenDocument style files,  Next: Creating one-off styles,  Prev: Configuring a document converter,  Up: Advanced topics in ODT export

12.8.11.2 Working with OpenDocument style files
...............................................

This section explores the internals of the ODT exporter and the means
by which it produces styled documents.  Read this section if you are
interested in exploring the automatic and custom OpenDocument styles
used by the exporter.

Factory styles
..............

The ODT exporter relies on two files for generating its output.  These
files are bundled with the distribution under the directory pointed to
by the variable `org-odt-styles-dir'.  The two files are:

   * `OrgOdtStyles.xml'

     This file contributes to the `styles.xml' file of the final `ODT'
     document.  This file gets modified for the following purposes:
       1. To control outline numbering based on user settings.

       2. To add styles generated by `htmlfontify.el' for fontification
          of code blocks.

   * `OrgOdtContentTemplate.xml'

     This file contributes to the `content.xml' file of the final `ODT'
     document.  The contents of the Org outline are inserted between the
     `<office:text>'...`</office:text>' elements of this file.

     Apart from serving as a template file for the final `content.xml',
     the file serves the following purposes:
       1. It contains automatic styles for formatting of tables which
          are referenced by the exporter.

       2. It contains `<text:sequence-decl>'...`</text:sequence-decl>'
          elements that control how various entities - tables, images,
          equations etc - are numbered.

Overriding factory styles
.........................

The following two variables control the location from which the ODT
exporter picks up the custom styles and content template files.  You can
customize these variables to override the factory styles used by the
exporter.

   * `org-export-odt-styles-file'

     Use this variable to specify the `styles.xml' that will be used in
     the final output.  You can specify one of the following values:

       1. A `styles.xml' file

          Use this file instead of the default `styles.xml'

       2. A `.odt' or `.ott' file

          Use the `styles.xml' contained in the specified OpenDocument
          Text or Template file

       3. A `.odt' or `.ott' file and a subset of files contained
          within them

          Use the `styles.xml' contained in the specified OpenDocument
          Text or Template file.  Additionally extract the specified
          member files and embed those within the final `ODT' document.

          Use this option if the `styles.xml' file references
          additional files like header and footer images.

       4. `nil'

          Use the default `styles.xml'

   * `org-export-odt-content-template-file'

     Use this variable to specify the blank `content.xml' that will be
     used in the final output.


File: org,  Node: Creating one-off styles,  Next: Customizing tables in ODT export,  Prev: Working with OpenDocument style files,  Up: Advanced topics in ODT export

12.8.11.3 Creating one-off styles
.................................

There are times when you would want one-off formatting in the exported
document.  You can achieve this by embedding raw OpenDocument XML in
the Org file.  The use of this feature is better illustrated with
couple of examples.

  1. Embedding ODT tags as part of regular text

     You can include simple OpenDocument tags by prefixing them with
     `@'.  For example, to highlight a region of text do the following:

          @<text:span text:style-name="Highlight">This is a
          highlighted text@</text:span>.  But this is a
          regular text.

     *Hint:* To see the above example in action, edit your `styles.xml'
     (*note Factory styles: x-orgodtstyles-xml.) and add a custom
     `Highlight' style as shown below.

          <style:style style:name="Highlight" style:family="text">
            <style:text-properties fo:background-color="#ff0000"/>
          </style:style>

  2. Embedding a one-line OpenDocument XML

     You can add a simple OpenDocument one-liner using the `#+ODT:'
     directive.  For example, to force a page break do the following:

          #+ODT: <text:p text:style-name="PageBreak"/>

     *Hint:* To see the above example in action, edit your `styles.xml'
     (*note Factory styles: x-orgodtstyles-xml.) and add a custom
     `PageBreak' style as shown below.

          <style:style style:name="PageBreak" style:family="paragraph"
          	     style:parent-style-name="Text_20_body">
            <style:paragraph-properties fo:break-before="page"/>
          </style:style>

  3. Embedding a block of OpenDocument XML

     You can add a large block of OpenDocument XML using the
     `#+BEGIN_ODT'...`#+END_ODT' construct.

     For example, to create a one-off paragraph that uses bold text, do
     the following:

          #+BEGIN_ODT
          <text:p text:style-name="Text_20_body_20_bold">
          This paragraph is specially formatted and uses bold text.
          </text:p>
          #+END_ODT



File: org,  Node: Customizing tables in ODT export,  Next: Validating OpenDocument XML,  Prev: Creating one-off styles,  Up: Advanced topics in ODT export

12.8.11.4 Customizing tables in ODT export
..........................................

You can override the default formatting of the table by specifying a
custom table style with the `#+ATTR_ODT' line.  For a discussion on
default formatting of tables *note Tables in ODT export::.

   This feature closely mimics the way table templates are defined in
the OpenDocument-v1.2 specification.(1)

Custom table styles - an illustration
.....................................

To have a quick preview of this feature, install the below setting and
export the table that follows.

     (setq org-export-odt-table-styles
           (append org-export-odt-table-styles
     	      '(("TableWithHeaderRowAndColumn" "Custom"
     		 ((use-first-row-styles . t)
     		  (use-first-column-styles . t)))
     		("TableWithFirstRowandLastRow" "Custom"
     		 ((use-first-row-styles . t)
     		  (use-last-row-styles . t))))))

     #+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
     | Name  | Phone | Age |
     | Peter |  1234 |  17 |
     | Anna  |  4321 |  25 |

   In the above example, you used a template named `Custom' and
installed two table styles with the names `TableWithHeaderRowAndColumn'
and `TableWithFirstRowandLastRow'.  (*Important:* The OpenDocument
styles needed for producing the above template have been pre-defined
for you.  These styles are available under the section marked `Custom
Table Template' in `OrgOdtContentTemplate.xml' (*note Factory styles:
x-orgodtcontenttemplate-xml.).  If you need additional templates you
have to define these styles yourselves.

Custom table styles - the nitty-gritty
......................................

To use this feature proceed as follows:

  1. Create a table template(2)

     A table template is nothing but a set of `table-cell' and
     `paragraph' styles for each of the following table cell categories:

        - Body

        - First column

        - Last column

        - First row

        - Last row

        - Even row

        - Odd row

        - Even column

        - Odd Column

     The names for the above styles must be chosen based on the name of
     the table template using a well-defined convention.

     The naming convention is better illustrated with an example.  For
     a table template with the name `Custom', the needed style names
     are listed in the following table.

     Table cell type   `table-cell' style          `paragraph' style
     ------------------------------------------------------------------------------- 

     Body              `CustomTableCell'           `CustomTableParagraph'
     First column      `CustomFirstColumnTableCell'`CustomFirstColumnTableParagraph'
     Last column       `CustomLastColumnTableCell' `CustomLastColumnTableParagraph'
     First row         `CustomFirstRowTableCell'   `CustomFirstRowTableParagraph'
     Last row          `CustomLastRowTableCell'    `CustomLastRowTableParagraph'
     Even row          `CustomEvenRowTableCell'    `CustomEvenRowTableParagraph'
     Odd row           `CustomOddRowTableCell'     `CustomOddRowTableParagraph'
     Even column       `CustomEvenColumnTableCell' `CustomEvenColumnTableParagraph'
     Odd column        `CustomOddColumnTableCell'  `CustomOddColumnTableParagraph'

     To create a table template with the name `Custom', define the above
     styles in the
     `<office:automatic-styles>'...`</office:automatic-styles>' element
     of the content template file (*note Factory styles:
     x-orgodtcontenttemplate-xml.).

  2. Define a table style(3)

     To define a table style, create an entry for the style in the
     variable `org-export-odt-table-styles' and specify the following:

        - the name of the table template created in step (1)

        - the set of cell styles in that template that are to be
          activated

     For example, the entry below defines two different table styles
     `TableWithHeaderRowAndColumn' and `TableWithFirstRowandLastRow'
     based on the same template `Custom'.  The styles achieve their
     intended effect by selectively activating the individual cell
     styles in that template.

          (setq org-export-odt-table-styles
                (append org-export-odt-table-styles
          	      '(("TableWithHeaderRowAndColumn" "Custom"
          		 ((use-first-row-styles . t)
          		  (use-first-column-styles . t)))
          		("TableWithFirstRowandLastRow" "Custom"
          		 ((use-first-row-styles . t)
          		  (use-last-row-styles . t))))))

  3. Associate a table with the table style

     To do this, specify the table style created in step (2) as part of
     the `ATTR_ODT' line as shown below.

          #+ATTR_ODT: :style "TableWithHeaderRowAndColumn"
          | Name  | Phone | Age |
          | Peter |  1234 |  17 |
          | Anna  |  4321 |  25 |

   ---------- Footnotes ----------

   (1) OpenDocument-v1.2 Specification
(http://docs.oasis-open.org/office/v1.2/OpenDocument-v1.2.html)

   (2) See the `<table:table-template>' element of the
OpenDocument-v1.2 specification

   (3) See the attributes `table:template-name',
`table:use-first-row-styles', `table:use-last-row-styles',
`table:use-first-column-styles', `table:use-last-column-styles',
`table:use-banding-rows-styles', and `table:use-banding-column-styles'
of the `<table:table>' element in the OpenDocument-v1.2 specification


File: org,  Node: Validating OpenDocument XML,  Prev: Customizing tables in ODT export,  Up: Advanced topics in ODT export

12.8.11.5 Validating OpenDocument XML
.....................................

Occasionally, you will discover that the document created by the ODT
exporter cannot be opened by your favorite application.  One of the
common reasons for this is that the `.odt' file is corrupt.  In such
cases, you may want to validate the document against the OpenDocument
RELAX NG Compact Syntax (RNC) schema.

   For de-compressing the `.odt' file(1): *note (emacs)File Archives::.
For general help with validation (and schema-sensitive editing) of XML
files: *note (nxml-mode)Introduction::.

   If you have ready access to OpenDocument `.rnc' files and the needed
schema-locating rules in a single folder, you can customize the variable
`org-export-odt-schema-dir' to point to that directory.  The ODT
exporter will take care of updating the `rng-schema-locating-files' for
you.

   ---------- Footnotes ----------

   (1) `.odt' files are nothing but `zip' archives


File: org,  Node: TaskJuggler export,  Next: Freemind export,  Prev: OpenDocument Text export,  Up: Exporting

12.9 TaskJuggler export
=======================

TaskJuggler (http://www.taskjuggler.org/) is a project management tool.
It provides an optimizing scheduler that computes your project time
lines and resource assignments based on the project outline and the
constraints that you have provided.

   The TaskJuggler exporter is a bit different from other exporters,
such as the `HTML' and LaTeX exporters for example, in that it does not
export all the nodes of a document or strictly follow the order of the
nodes in the document.

   Instead the TaskJuggler exporter looks for a tree that defines the
tasks and a optionally tree that defines the resources for this
project.  It then creates a TaskJuggler file based on these trees and
the attributes defined in all the nodes.

12.9.1 TaskJuggler export commands
----------------------------------

`C-c C-e j     (`org-export-as-taskjuggler')'
     Export as TaskJuggler file.

`C-c C-e J     (`org-export-as-taskjuggler-and-open')'
     Export as TaskJuggler file and then open the file with
     TaskJugglerUI.

12.9.2 Tasks
------------

Create your tasks as you usually do with Org mode.  Assign efforts to
each task using properties (it is easiest to do this in the column
view).  You should end up with something similar to the example by
Peter Jones in
`http://www.contextualdevelopment.com/static/artifacts/articles/2008/project-planning/project-planning.org'.
Now mark the top node of your tasks with a tag named
`:taskjuggler_project:' (or whatever you customized
`org-export-taskjuggler-project-tag' to).  You are now ready to export
the project plan with `C-c C-e J' which will export the project plan and
open a gantt chart in TaskJugglerUI.

12.9.3 Resources
----------------

Next you can define resources and assign those to work on specific
tasks.  You can group your resources hierarchically.  Tag the top node
of the resources with `:taskjuggler_resource:' (or whatever you
customized `org-export-taskjuggler-resource-tag' to).  You can
optionally assign an identifier (named `resource_id') to the resources
(using the standard Org properties commands, *note Property syntax::)
or you can let the exporter generate identifiers automatically (the
exporter picks the first word of the headline as the identifier as long
as it is unique--see the documentation of
`org-taskjuggler-get-unique-id').  Using that identifier you can then
allocate resources to tasks.  This is again done with the `allocate'
property on the tasks.  Do this in column view or when on the task type
`C-c C-x p allocate <RET> <resource_id> <RET>'.

   Once the allocations are done you can again export to TaskJuggler
and check in the Resource Allocation Graph which person is working on
what task at what time.

12.9.4 Export of properties
---------------------------

The exporter also takes TODO state information into consideration, i.e.
if a task is marked as done it will have the corresponding attribute in
TaskJuggler (`complete 100').  Also it will export any property on a
task resource or resource node which is known to TaskJuggler, such as
`limits', `vacation', `shift', `booking', `efficiency', `journalentry',
`rate' for resources or `account', `start', `note', `duration', `end',
`journalentry', `milestone', `reference', `responsible', `scheduling',
etc for tasks.

12.9.5 Dependencies
-------------------

The exporter will handle dependencies that are defined in the tasks
either with the `ORDERED' attribute (*note TODO dependencies::), with
the `BLOCKER' attribute (see `org-depend.el') or alternatively with a
`depends' attribute.  Both the `BLOCKER' and the `depends' attribute
can be either `previous-sibling' or a reference to an identifier (named
`task_id') which is defined for another task in the project.  `BLOCKER'
and the `depends' attribute can define multiple dependencies separated
by either space or comma.  You can also specify optional attributes on
the dependency by simply appending it.  The following examples should
illustrate this:

     * Preparation
       :PROPERTIES:
       :task_id:  preparation
       :ORDERED:  t
       :END:
     * Training material
       :PROPERTIES:
       :task_id:  training_material
       :ORDERED:  t
       :END:
     ** Markup Guidelines
        :PROPERTIES:
        :Effort:   2d
        :END:
     ** Workflow Guidelines
        :PROPERTIES:
        :Effort:   2d
        :END:
     * Presentation
       :PROPERTIES:
       :Effort:   2d
       :BLOCKER:  training_material { gapduration 1d } preparation
       :END:

12.9.6 Reports
--------------

TaskJuggler can produce many kinds of reports (e.g. gantt chart,
resource allocation, etc).  The user defines what kind of reports
should be generated for a project in the TaskJuggler file.  The
exporter will automatically insert some default reports in the file.
These defaults are defined in `org-export-taskjuggler-default-reports'.
They can be modified using customize along with a number of other
options.  For a more complete list, see `M-x customize-group <RET>
org-export-taskjuggler <RET>'.

   For more information and examples see the Org-taskjuggler tutorial at
`http://orgmode.org/worg/org-tutorials/org-taskjuggler.html'.


File: org,  Node: Freemind export,  Next: XOXO export,  Prev: TaskJuggler export,  Up: Exporting

12.10 Freemind export
=====================

The Freemind exporter was written by Lennart Borgman.

`C-c C-e m     (`org-export-as-freemind')'
     Export as Freemind mind map.  For an Org file `myfile.org', the
     Freemind file will be `myfile.mm'.


File: org,  Node: XOXO export,  Next: iCalendar export,  Prev: Freemind export,  Up: Exporting

12.11 XOXO export
=================

Org mode contains an exporter that produces XOXO-style output.
Currently, this exporter only handles the general outline structure and
does not interpret any additional Org mode features.

`C-c C-e x     (`org-export-as-xoxo')'
     Export as XOXO file.  For an Org file `myfile.org', the XOXO file
     will be `myfile.html'.  

`C-c C-e v x'
     Export only the visible part of the document.


File: org,  Node: iCalendar export,  Prev: XOXO export,  Up: Exporting

12.12 iCalendar export
======================

Some people use Org mode for keeping track of projects, but still
prefer a standard calendar application for anniversaries and
appointments.  In this case it can be useful to show deadlines and
other time-stamped items in Org files in the calendar application.  Org
mode can export calendar information in the standard iCalendar format.
If you also want to have TODO entries included in the export, configure
the variable `org-icalendar-include-todo'.  Plain timestamps are
exported as VEVENT, and TODO items as VTODO.  It will also create
events from deadlines that are in non-TODO items.  Deadlines and
scheduling dates in TODO items will be used to set the start and due
dates for the TODO entry(1).  As categories, it will use the tags
locally defined in the heading, and the file/tree category(2).  See the
variable `org-icalendar-alarm-time' for a way to assign alarms to
entries with a time.

   The iCalendar standard requires each entry to have a globally unique
identifier (UID).  Org creates these identifiers during export.  If you
set the variable `org-icalendar-store-UID', the UID will be stored in
the `:ID:' property of the entry and re-used next time you report this
entry.  Since a single entry can give rise to multiple iCalendar
entries (as a timestamp, a deadline, a scheduled item, and as a TODO
item), Org adds prefixes to the UID, depending on what triggered the
inclusion of the entry.  In this way the UID remains unique, but a
synchronization program can still figure out from which entry all the
different instances originate.

`C-c C-e i     (`org-export-icalendar-this-file')'
     Create iCalendar entries for the current file and store them in
     the same directory, using a file extension `.ics'.  

`C-c C-e I     (`org-export-icalendar-all-agenda-files')'
     Like `C-c C-e i', but do this for all files in `org-agenda-files'.
     For each of these files, a separate iCalendar file will be written.  

`C-c C-e c     (`org-export-icalendar-combine-agenda-files')'
     Create a single large iCalendar file from all files in
     `org-agenda-files' and write it to the file given by
     `org-combined-agenda-icalendar-file'.

   The export will honor SUMMARY, DESCRIPTION and LOCATION(3)
properties if the selected entries have them.  If not, the summary will
be derived from the headline, and the description from the body
(limited to `org-icalendar-include-body' characters).

   How this calendar is best read and updated, depends on the
application you are using.  The FAQ covers this issue.

   ---------- Footnotes ----------

   (1) See the variables `org-icalendar-use-deadline' and
`org-icalendar-use-scheduled'.

   (2) To add inherited tags or the TODO state, configure the variable
`org-icalendar-categories'.

   (3) The LOCATION property can be inherited from higher in the
hierarchy if you configure `org-use-property-inheritance' accordingly.


File: org,  Node: Publishing,  Next: Working With Source Code,  Prev: Exporting,  Up: Top

13 Publishing
*************

Org includes a publishing management system that allows you to configure
automatic HTML conversion of _projects_ composed of interlinked org
files.  You can also configure Org to automatically upload your
exported HTML pages and related attachments, such as images and source
code files, to a web server.

   You can also use Org to convert files into PDF, or even combine HTML
and PDF conversion so that files are available in both formats on the
server.

   Publishing has been contributed to Org by David O'Toole.

* Menu:

* Configuration::               Defining projects
* Uploading files::             How to get files up on the server
* Sample configuration::        Example projects
* Triggering publication::      Publication commands


File: org,  Node: Configuration,  Next: Uploading files,  Prev: Publishing,  Up: Publishing

13.1 Configuration
==================

Publishing needs significant configuration to specify files, destination
and many other properties of a project.

* Menu:

* Project alist::               The central configuration variable
* Sources and destinations::    From here to there
* Selecting files::             What files are part of the project?
* Publishing action::           Setting the function doing the publishing
* Publishing options::          Tweaking HTML/LaTeX export
* Publishing links::            Which links keep working after publishing?
* Sitemap::                     Generating a list of all pages
* Generating an index::         An index that reaches across pages


File: org,  Node: Project alist,  Next: Sources and destinations,  Prev: Configuration,  Up: Configuration

13.1.1 The variable `org-publish-project-alist'
-----------------------------------------------

Publishing is configured almost entirely through setting the value of
one variable, called `org-publish-project-alist'.  Each element of the
list configures one project, and may be in one of the two following
forms:

        ("project-name" :property value :property value ...)
          i.e. a well-formed property list with alternating keys and values
     or
        ("project-name" :components ("project-name" "project-name" ...))

   In both cases, projects are configured by specifying property
values.  A project defines the set of files that will be published, as
well as the publishing configuration to use when publishing those
files.  When a project takes the second form listed above, the
individual members of the `:components' property are taken to be
sub-projects, which group together files requiring different publishing
options.  When you publish such a "meta-project", all the components
will also be published, in the sequence given.


File: org,  Node: Sources and destinations,  Next: Selecting files,  Prev: Project alist,  Up: Configuration

13.1.2 Sources and destinations for files
-----------------------------------------

Most properties are optional, but some should always be set.  In
particular, Org needs to know where to look for source files, and where
to put published files.

`:base-directory'      Directory containing publishing source files
`:publishing-directory'Directory where output files will be published.
                       You can directly publish to a webserver using a
                       file name syntax appropriate for the Emacs
                       `tramp' package.  Or you can publish to a local
                       directory and use external tools to upload your
                       website (*note Uploading files::).
`:preparation-function'Function or list of functions to be called before
                       starting the publishing process, for example, to
                       run `make' for updating files to be published.
                       The project property list is scoped into this
                       call as the variable `project-plist'.
`:completion-function' Function or list of functions called after
                       finishing the publishing process, for example, to
                       change permissions of the resulting files.  The
                       project property list is scoped into this call as
                       the variable `project-plist'.


File: org,  Node: Selecting files,  Next: Publishing action,  Prev: Sources and destinations,  Up: Configuration

13.1.3 Selecting files
----------------------

By default, all files with extension `.org' in the base directory are
considered part of the project.  This can be modified by setting the
properties
`:base-extension'  Extension (without the dot!) of source files.  This
                   actually is a regular expression.  Set this to the
                   symbol `any' if you want to get all files in
                   `:base-directory', even without extension.
`:exclude'         Regular expression to match file names that should
                   not be published, even though they have been selected
                   on the basis of their extension.
`:include'         List of files to be included regardless of
                   `:base-extension' and `:exclude'.
`:recursive'       Non-nil means, check base-directory recursively for
                   files to publish.


File: org,  Node: Publishing action,  Next: Publishing options,  Prev: Selecting files,  Up: Configuration

13.1.4 Publishing action
------------------------

Publishing means that a file is copied to the destination directory and
possibly transformed in the process.  The default transformation is to
export Org files as HTML files, and this is done by the function
`org-publish-org-to-html' which calls the HTML exporter (*note HTML
export::).  But you also can publish your content as PDF files using
`org-publish-org-to-pdf', or as `ascii', `latin1' or `utf8' encoded
files using the corresponding functions.  If you want to publish the
Org file itself, but with archived, commented, and tag-excluded trees
removed, use `org-publish-org-to-org' and set the parameters
`:plain-source' and/or `:htmlized-source'.  This will produce
`file.org' and `file.org.html' in the publishing directory(1).  Other
files like images only need to be copied to the publishing destination;
for this you may use `org-publish-attachment'.  For non-Org files, you
always need to specify the publishing function:

`:publishing-function' Function executing the publication of a file.
                       This may also be a list of functions, which will
                       all be called in turn.
`:plain-source'        Non-nil means, publish plain source.
`:htmlized-source'     Non-nil means, publish htmlized source.

   The function must accept three arguments: a property list containing
at least a `:publishing-directory' property, the name of the file to be
published, and the path to the publishing directory of the output file.
It should take the specified file, make the necessary transformation
(if any) and place the result into the destination folder.

   ---------- Footnotes ----------

   (1) `file-source.org' and `file-source.org.html' if source and
publishing directories are equal.  Note that with this kind of setup,
you need to add `:exclude "-source\\.org"' to the project definition in
`org-publish-project-alist' to prevent the published source files from
being considered as new org files the next time the project is
published.


File: org,  Node: Publishing options,  Next: Publishing links,  Prev: Publishing action,  Up: Configuration

13.1.5 Options for the HTML/LaTeX exporters
-------------------------------------------

The property list can be used to set many export options for the HTML
and LaTeX exporters.  In most cases, these properties correspond to user
variables in Org.  The table below lists these properties along with
the variable they belong to.  See the documentation string for the
respective variable for details.

`:link-up'              `org-export-html-link-up'
`:link-home'            `org-export-html-link-home'
`:language'             `org-export-default-language'
`:customtime'           `org-display-custom-times'
`:headline-levels'      `org-export-headline-levels'
`:section-numbers'      `org-export-with-section-numbers'
`:section-number-format'`org-export-section-number-format'
`:table-of-contents'    `org-export-with-toc'
`:preserve-breaks'      `org-export-preserve-breaks'
`:archived-trees'       `org-export-with-archived-trees'
`:emphasize'            `org-export-with-emphasize'
`:sub-superscript'      `org-export-with-sub-superscripts'
`:special-strings'      `org-export-with-special-strings'
`:footnotes'            `org-export-with-footnotes'
`:drawers'              `org-export-with-drawers'
`:tags'                 `org-export-with-tags'
`:todo-keywords'        `org-export-with-todo-keywords'
`:tasks'                `org-export-with-tasks'
`:priority'             `org-export-with-priority'
`:TeX-macros'           `org-export-with-TeX-macros'
`:LaTeX-fragments'      `org-export-with-LaTeX-fragments'
`:latex-listings'       `org-export-latex-listings'
`:skip-before-1st-heading'`org-export-skip-text-before-1st-heading'
`:fixed-width'          `org-export-with-fixed-width'
`:timestamps'           `org-export-with-timestamps'
`:author'               `user-full-name'
`:email'                `user-mail-address' : `addr;addr;..'
`:author-info'          `org-export-author-info'
`:email-info'           `org-export-email-info'
`:creator-info'         `org-export-creator-info'
`:tables'               `org-export-with-tables'
`:table-auto-headline'  `org-export-highlight-first-table-line'
`:style-include-default'`org-export-html-style-include-default'
`:style-include-scripts'`org-export-html-style-include-scripts'
`:style'                `org-export-html-style'
`:style-extra'          `org-export-html-style-extra'
`:convert-org-links'    `org-export-html-link-org-files-as-html'
`:inline-images'        `org-export-html-inline-images'
`:html-extension'       `org-export-html-extension'
`:html-preamble'        `org-export-html-preamble'
`:html-postamble'       `org-export-html-postamble'
`:xml-declaration'      `org-export-html-xml-declaration'
`:html-table-tag'       `org-export-html-table-tag'
`:expand-quoted-html'   `org-export-html-expand'
`:timestamp'            `org-export-html-with-timestamp'
`:publishing-directory' `org-export-publishing-directory'
`:select-tags'          `org-export-select-tags'
`:exclude-tags'         `org-export-exclude-tags'
`:latex-image-options'  `org-export-latex-image-default-option'

   Most of the `org-export-with-*' variables have the same effect in
both HTML and LaTeX exporters, except for `:TeX-macros' and
`:LaTeX-fragments' options, respectively `nil' and `t' in the LaTeX
export.  See `org-export-plist-vars' to check this list of options.

   When a property is given a value in `org-publish-project-alist', its
setting overrides the value of the corresponding user variable (if any)
during publishing.  Options set within a file (*note Export options::),
however, override everything.


File: org,  Node: Publishing links,  Next: Sitemap,  Prev: Publishing options,  Up: Configuration

13.1.6 Links between published files
------------------------------------

To create a link from one Org file to another, you would use something
like `[[file:foo.org][The foo]]' or simply `file:foo.org.' (*note
Hyperlinks::).  When published, this link becomes a link to `foo.html'.
In this way, you can interlink the pages of your "org web" project and
the links will work as expected when you publish them to HTML.  If you
also publish the Org source file and want to link to that, use an
`http:' link instead of a `file:' link, because `file:' links are
converted to link to the corresponding `html' file.

   You may also link to related files, such as images.  Provided you
are careful with relative file names, and provided you have also
configured Org to upload the related files, these links will work too.
See *note Complex example::, for an example of this usage.

   Sometimes an Org file to be published may contain links that are
only valid in your production environment, but not in the publishing
location.  In this case, use the property

`:link-validation-function'   Function to validate links

to define a function for checking link validity.  This function must
accept two arguments, the file name and a directory relative to which
the file name is interpreted in the production environment.  If this
function returns `nil', then the HTML generator will only insert a
description into the HTML file, but no link.  One option for this
function is `org-publish-validate-link' which checks if the given file
is part of any project in `org-publish-project-alist'.


File: org,  Node: Sitemap,  Next: Generating an index,  Prev: Publishing links,  Up: Configuration

13.1.7 Generating a sitemap
---------------------------

The following properties may be used to control publishing of a map of
files for a given project.

`:auto-sitemap'           When non-nil, publish a sitemap during
                          `org-publish-current-project' or
                          `org-publish-all'.
`:sitemap-filename'       Filename for output of sitemap.  Defaults to
                          `sitemap.org' (which becomes `sitemap.html').
`:sitemap-title'          Title of sitemap page.  Defaults to name of
                          file.
`:sitemap-function'       Plug-in function to use for generation of the
                          sitemap.  Defaults to
                          `org-publish-org-sitemap', which generates a
                          plain list of links to all files in the
                          project.
`:sitemap-sort-folders'   Where folders should appear in the sitemap.
                          Set this to `first' (default) or `last' to
                          display folders first or last, respectively.
                          Any other value will mix files and folders.
`:sitemap-sort-files'     How the files are sorted in the site map.  Set
                          this to `alphabetically' (default),
                          `chronologically' or `anti-chronologically'.
                          `chronologically' sorts the files with older
                          date first while `anti-chronologically' sorts
                          the files with newer date first.
                          `alphabetically' sorts the files
                          alphabetically.  The date of a file is
                          retrieved with `org-publish-find-date'.
`:sitemap-ignore-case'    Should sorting be case-sensitive?  Default
                          `nil'.
`:sitemap-file-entry-format'With this option one can tell how a sitemap's
                          entry is formatted in the sitemap.  This is a
                          format string with some escape sequences: `%t'
                          stands for the title of the file, `%a' stands
                          for the author of the file and `%d' stands for
                          the date of the file.  The date is retrieved
                          with the `org-publish-find-date' function and
                          formatted with
                          `org-publish-sitemap-date-format'.  Default
                          `%t'.
`:sitemap-date-format'    Format string for the `format-time-string'
                          function that tells how a sitemap entry's date
                          is to be formatted.  This property bypasses
                          `org-publish-sitemap-date-format' which
                          defaults to `%Y-%m-%d'.
`:sitemap-sans-extension' When non-nil, remove filenames' extensions
                          from the generated sitemap.  Useful to have
                          cool URIs (see
                          `http://www.w3.org/Provider/Style/URI').
                          Defaults to `nil'.


File: org,  Node: Generating an index,  Prev: Sitemap,  Up: Configuration

13.1.8 Generating an index
--------------------------

Org mode can generate an index across the files of a publishing project.

`:makeindex'       When non-nil, generate in index in the file
                   `theindex.org' and publish it as `theindex.html'.

   The file will be created when first publishing a project with the
`:makeindex' set.  The file only contains a statement `#+include:
"theindex.inc"'.  You can then build around this include statement by
adding a title, style information, etc.


File: org,  Node: Uploading files,  Next: Sample configuration,  Prev: Configuration,  Up: Publishing

13.2 Uploading files
====================

For those people already utilizing third party sync tools such as
`rsync' or `unison', it might be preferable not to use the built in
remote publishing facilities of Org mode which rely heavily on Tramp.
Tramp, while very useful and powerful, tends not to be so efficient for
multiple file transfer and has been known to cause problems under heavy
usage.

   Specialized synchronization utilities offer several advantages.  In
addition to timestamp comparison, they also do content and
permissions/attribute checks.  For this reason you might prefer to
publish your web to a local directory (possibly even in place with your
Org files) and then use `unison' or `rsync' to do the synchronization
with the remote host.

   Since Unison (for example) can be configured as to which files to
transfer to a certain remote destination, it can greatly simplify the
project publishing definition.  Simply keep all files in the correct
location, process your Org files with `org-publish' and let the
synchronization tool do the rest.  You do not need, in this scenario,
to include attachments such as `jpg', `css' or `gif' files in the
project definition since the 3rd party tool syncs them.

   Publishing to a local directory is also much faster than to a remote
one, so that you can afford more easily to republish entire projects.
If you set `org-publish-use-timestamps-flag' to `nil', you gain the main
benefit of re-including any changed external files such as source
example files you might include with `#+INCLUDE'.  The timestamp
mechanism in Org is not smart enough to detect if included files have
been modified.


File: org,  Node: Sample configuration,  Next: Triggering publication,  Prev: Uploading files,  Up: Publishing

13.3 Sample configuration
=========================

Below we provide two example configurations.  The first one is a simple
project publishing only a set of Org files.  The second example is more
complex, with a multi-component project.

* Menu:

* Simple example::              One-component publishing
* Complex example::             A multi-component publishing example


File: org,  Node: Simple example,  Next: Complex example,  Prev: Sample configuration,  Up: Sample configuration

13.3.1 Example: simple publishing configuration
-----------------------------------------------

This example publishes a set of Org files to the `public_html'
directory on the local machine.

     (setq org-publish-project-alist
           '(("org"
              :base-directory "~/org/"
              :publishing-directory "~/public_html"
              :section-numbers nil
              :table-of-contents nil
              :style "<link rel=\"stylesheet\"
                     href=\"../other/mystyle.css\"
                     type=\"text/css\"/>")))


File: org,  Node: Complex example,  Prev: Simple example,  Up: Sample configuration

13.3.2 Example: complex publishing configuration
------------------------------------------------

This more complicated example publishes an entire website, including
Org files converted to HTML, image files, Emacs Lisp source code, and
style sheets.  The publishing directory is remote and private files are
excluded.

   To ensure that links are preserved, care should be taken to replicate
your directory structure on the web server, and to use relative file
paths.  For example, if your Org files are kept in `~/org' and your
publishable images in `~/images', you would link to an image with
     file:../images/myimage.png
   On the web server, the relative path to the image should be the
same.  You can accomplish this by setting up an "images" folder in the
right place on the web server, and publishing images to it.

     (setq org-publish-project-alist
           '(("orgfiles"
               :base-directory "~/org/"
               :base-extension "org"
               :publishing-directory "/ssh:user@host:~/html/notebook/"
               :publishing-function org-publish-org-to-html
               :exclude "PrivatePage.org"   ;; regexp
               :headline-levels 3
               :section-numbers nil
               :table-of-contents nil
               :style "<link rel=\"stylesheet\"
                       href=\"../other/mystyle.css\" type=\"text/css\"/>"
               :html-preamble t)

              ("images"
               :base-directory "~/images/"
               :base-extension "jpg\\|gif\\|png"
               :publishing-directory "/ssh:user@host:~/html/images/"
               :publishing-function org-publish-attachment)

              ("other"
               :base-directory "~/other/"
               :base-extension "css\\|el"
               :publishing-directory "/ssh:user@host:~/html/other/"
               :publishing-function org-publish-attachment)
              ("website" :components ("orgfiles" "images" "other"))))


File: org,  Node: Triggering publication,  Prev: Sample configuration,  Up: Publishing

13.4 Triggering publication
===========================

Once properly configured, Org can publish with the following commands:

`C-c C-e X     (`org-publish')'
     Prompt for a specific project and publish all files that belong to
     it.  

`C-c C-e P     (`org-publish-current-project')'
     Publish the project containing the current file.  

`C-c C-e F     (`org-publish-current-file')'
     Publish only the current file.  

`C-c C-e E     (`org-publish-all')'
     Publish every project.

   Org uses timestamps to track when a file has changed.  The above
functions normally only publish changed files.  You can override this
and force publishing of all files by giving a prefix argument to any of
the commands above, or by customizing the variable
`org-publish-use-timestamps-flag'.  This may be necessary in particular
if files include other files via `#+SETUPFILE:' or `#+INCLUDE:'.


File: org,  Node: Working With Source Code,  Next: Miscellaneous,  Prev: Publishing,  Up: Top

14 Working with source code
***************************

Source code can be included in Org mode documents using a `src' block,
e.g.

     #+BEGIN_SRC emacs-lisp
       (defun org-xor (a b)
          "Exclusive or."
          (if a (not b) b))
     #+END_SRC

   Org mode provides a number of features for working with live source
code, including editing of code blocks in their native major-mode,
evaluation of code blocks, converting code blocks into source files
(known as "tangling" in literate programming), and exporting code
blocks and their results in several formats.  This functionality was
contributed by Eric Schulte and Dan Davison, and was originally named
Org-babel.

   The following sections describe Org mode's code block handling
facilities.

* Menu:

* Structure of code blocks::    Code block syntax described
* Editing source code::         Language major-mode editing
* Exporting code blocks::       Export contents and/or results
* Extracting source code::      Create pure source code files
* Evaluating code blocks::      Place results of evaluation in the Org mode buffer
* Library of Babel::            Use and contribute to a library of useful code blocks
* Languages::                   List of supported code block languages
* Header arguments::            Configure code block functionality
* Results of evaluation::       How evaluation results are handled
* Noweb reference syntax::      Literate programming in Org mode
* Key bindings and useful functions::  Work quickly with code blocks
* Batch execution::             Call functions from the command line


File: org,  Node: Structure of code blocks,  Next: Editing source code,  Prev: Working With Source Code,  Up: Working With Source Code

14.1 Structure of code blocks
=============================

Live code blocks can be specified with a `src' block or inline.(1)  The
structure of a `src' block is

     #+NAME: <name>
     #+BEGIN_SRC <language> <switches> <header arguments>
       <body>
     #+END_SRC

   The `#+NAME:' line is optional, and can be used to name the code
block.  Live code blocks require that a language be specified on the
`#+BEGIN_SRC' line.  Switches and header arguments are optional.  

   Live code blocks can also be specified inline using

     src_<language>{<body>}

   or

     src_<language>[<header arguments>]{<body>}

`<#+NAME: name>'
     This line associates a name with the code block.  This is similar
     to the `#+TBLNAME: NAME' lines that can be used to name tables in
     Org mode files.  Referencing the name of a code block makes it
     possible to evaluate the block from other places in the file, from
     other files, or from Org mode table formulas (see *note The
     spreadsheet::).  Names are assumed to be unique and the behavior
     of Org mode when two or more blocks share the same name is
     undefined.  

`<language>'
     The language of the code in the block (see *note Languages::).  

`<switches>'
     Optional switches control code block export (see the discussion of
     switches in *note Literal examples::) 

`<header arguments>'
     Optional header arguments control many aspects of evaluation,
     export and tangling of code blocks (see *note Header arguments::).
     Header arguments can also be set on a per-buffer or per-subtree
     basis using properties.

`source code, header arguments'

`<body>'
     Source code in the specified language.

   ---------- Footnotes ----------

   (1) Note that `src' blocks may be inserted using Org mode's *note
Easy Templates:: system


File: org,  Node: Editing source code,  Next: Exporting code blocks,  Prev: Structure of code blocks,  Up: Working With Source Code

14.2 Editing source code
========================

Use `C-c '' to edit the current code block.  This brings up a language
major-mode edit buffer containing the body of the code block.  Saving
this buffer will write the new contents back to the Org buffer.  Use
`C-c '' again to exit.

   The `org-src-mode' minor mode will be active in the edit buffer.  The
following variables can be used to configure the behavior of the edit
buffer.  See also the customization group `org-edit-structure' for
further configuration options.

`org-src-lang-modes'
     If an Emacs major-mode named `<lang>-mode' exists, where `<lang>'
     is the language named in the header line of the code block, then
     the edit buffer will be placed in that major-mode.  This variable
     can be used to map arbitrary language names to existing major
     modes.

`org-src-window-setup'
     Controls the way Emacs windows are rearranged when the edit buffer
     is created.

`org-src-preserve-indentation'
     This variable is especially useful for tangling languages such as
     Python, in which whitespace indentation in the output is critical.

`org-src-ask-before-returning-to-edit-buffer'
     By default, Org will ask before returning to an open edit buffer.
     Set this variable to nil to switch without asking.

   To turn on native code fontification in the _Org_ buffer, configure
the variable `org-src-fontify-natively'.


File: org,  Node: Exporting code blocks,  Next: Extracting source code,  Prev: Editing source code,  Up: Working With Source Code

14.3 Exporting code blocks
==========================

It is possible to export the _code_ of code blocks, the _results_ of
code block evaluation, _both_ the code and the results of code block
evaluation, or _none_.  For most languages, the default exports code.
However, for some languages (e.g. `ditaa') the default exports the
results of code block evaluation.  For information on exporting code
block bodies, see *note Literal examples::.

   The `:exports' header argument can be used to specify export
behavior:

Header arguments:
.................

`:exports code'
     The default in most languages.  The body of the code block is
     exported, as described in *note Literal examples::.

`:exports results'
     The code block will be evaluated and the results will be placed in
     the Org mode buffer for export, either updating previous results
     of the code block located anywhere in the buffer or, if no
     previous results exist, placing the results immediately after the
     code block.  The body of the code block will not be exported.

`:exports both'
     Both the code block and its results will be exported.

`:exports none'
     Neither the code block nor its results will be exported.

   It is possible to inhibit the evaluation of code blocks during
export.  Setting the `org-export-babel-evaluate' variable to `nil' will
ensure that no code blocks are evaluated as part of the export process.
This can be useful in situations where potentially untrusted Org mode
files are exported in an automated fashion, for example when Org mode
is used as the markup language for a wiki.


File: org,  Node: Extracting source code,  Next: Evaluating code blocks,  Prev: Exporting code blocks,  Up: Working With Source Code

14.4 Extracting source code
===========================

Creating pure source code files by extracting code from source blocks is
referred to as "tangling"--a term adopted from the literate programming
community.  During "tangling" of code blocks their bodies are expanded
using `org-babel-expand-src-block' which can expand both variable and
"noweb" style references  (see *note Noweb reference syntax::).

Header arguments
................

`:tangle no'
     The default.  The code block is not included in the tangled output.

`:tangle yes'
     Include the code block in the tangled output.  The output file
     name is the name of the org file with the extension `.org'
     replaced by the extension for the block language.

`:tangle filename'
     Include the code block in the tangled output to file `filename'.

Functions
.........

`org-babel-tangle'
     Tangle the current file.  Bound to `C-c C-v t'.

`org-babel-tangle-file'
     Choose a file to tangle.  Bound to `C-c C-v f'.

Hooks
.....

`org-babel-post-tangle-hook'
     This hook is run from within code files tangled by
     `org-babel-tangle'.  Example applications could include
     post-processing, compilation or evaluation of tangled code files.


File: org,  Node: Evaluating code blocks,  Next: Library of Babel,  Prev: Extracting source code,  Up: Working With Source Code

14.5 Evaluating code blocks
===========================

Code blocks can be evaluated(1) and the results of evaluation
optionally placed in the Org mode buffer.  The results of evaluation
are placed following a line that begins by default with `#+RESULTS' and
optionally a cache identifier and/or the name of the evaluated code
block.  The default value of `#+RESULTS' can be changed with the
customizable variable `org-babel-results-keyword'.

   By default, the evaluation facility is only enabled for Lisp code
blocks specified as `emacs-lisp'. However, source code blocks in many
languages can be evaluated within Org mode (see *note Languages:: for a
list of supported languages and *note Structure of code blocks:: for
information on the syntax used to define a code block).

   There are a number of ways to evaluate code blocks.  The simplest is
to press `C-c C-c' or `C-c C-v e' with the point on a code block(2).
This will call the `org-babel-execute-src-block' function to evaluate
the block and insert its results into the Org mode buffer.  

   It is also possible to evaluate named code blocks from anywhere in an
Org mode buffer or an Org mode table. Live code blocks located in the
current Org mode buffer or in the "Library of Babel" (see *note Library
of Babel::) can be executed.  Named code blocks can be executed with a
separate `#+CALL:' line or inline within a block of text.

   The syntax of the `#+CALL:' line is

     #+CALL: <name>(<arguments>)
     #+CALL: <name>[<inside header arguments>](<arguments>) <end header arguments>

   The syntax for inline evaluation of named code blocks is

     ... call_<name>(<arguments>) ...
     ... call_<name>[<inside header arguments>](<arguments>)[<end header arguments>] ...

`<name>'
     The name of the code block to be evaluated (see *note Structure of
     code blocks::).

`<arguments>'
     Arguments specified in this section will be passed to the code
     block.  These arguments use standard function call syntax, rather
     than header argument syntax.  For example, a `#+CALL:' line that
     passes the number four to a code block named `double', which
     declares the header argument `:var n=2', would be written as
     `#+CALL: double(n=4)'.

`<inside header arguments>'
     Inside header arguments are passed through and applied to the
     named code block.  These arguments use header argument syntax
     rather than standard function call syntax.  Inside header
     arguments affect how the code block is evaluated.  For example,
     `[:results output]' will collect the results of everything printed
     to `STDOUT' during execution of the code block.

`<end header arguments>'
     End header arguments are applied to the calling instance and do
     not affect evaluation of the named code block.  They affect how
     the results are incorporated into the Org mode buffer and how the
     call line is exported.  For example, `:results html' will insert
     the results of the call line evaluation in the Org buffer, wrapped
     in a `BEGIN_HTML:' block.

     For more examples of passing header arguments to `#+CALL:' lines
     see *note Header arguments in function calls::.

   ---------- Footnotes ----------

   (1) Whenever code is evaluated there is a potential for that code to
do harm.  Org mode provides safeguards to ensure that code is only
evaluated after explicit confirmation from the user.  For information
on these safeguards (and on how to disable them) see *note Code
evaluation security::.

   (2) The `org-babel-no-eval-on-ctrl-c-ctrl-c' variable can be used to
remove code evaluation from the `C-c C-c' key binding.


File: org,  Node: Library of Babel,  Next: Languages,  Prev: Evaluating code blocks,  Up: Working With Source Code

14.6 Library of Babel
=====================

The "Library of Babel" consists of code blocks that can be called from
any Org mode file.  Code blocks defined in the "Library of Babel" can
be called remotely as if they were in the current Org mode buffer (see
*note Evaluating code blocks:: for information on the syntax of remote
code block evaluation).

   The central repository of code blocks in the "Library of Babel" is
housed in an Org mode file located in the `contrib' directory of Org
mode.

   Users can add code blocks they believe to be generally useful to
their "Library of Babel."  The code blocks can be stored in any Org
mode file and then loaded into the library with `org-babel-lob-ingest'.

   Code blocks located in any Org mode file can be loaded into the
"Library of Babel" with the `org-babel-lob-ingest' function, bound to
`C-c C-v i'.


File: org,  Node: Languages,  Next: Header arguments,  Prev: Library of Babel,  Up: Working With Source Code

14.7 Languages
==============

Code blocks in the following languages are supported.

Language             Identifier             Language         Identifier
Asymptote            asymptote              Awk              awk
Emacs Calc           calc                   C                C
C++                  C++                    Clojure          clojure
CSS                  css                    ditaa            ditaa
Graphviz             dot                    Emacs Lisp       emacs-lisp
gnuplot              gnuplot                Haskell          haskell
Java                 java                                    
Javascript           js                     LaTeX            latex
Ledger               ledger                 Lisp             lisp
Lilypond             lilypond               MATLAB           matlab
Mscgen               mscgen                 Objective Caml   ocaml
Octave               octave                 Org mode         org
Oz                   oz                     Perl             perl
Plantuml             plantuml               Python           python
R                    R                      Ruby             ruby
Sass                 sass                   Scheme           scheme
GNU Screen           screen                 shell            sh
SQL                  sql                    SQLite           sqlite

   Language-specific documentation is available for some languages.  If
available, it can be found at
`http://orgmode.org/worg/org-contrib/babel/languages'.

   The `org-babel-load-languages' controls which languages are enabled
for evaluation (by default only `emacs-lisp' is enabled).  This
variable can be set using the customization interface or by adding code
like the following to your emacs configuration.

     The following disables `emacs-lisp' evaluation and enables
     evaluation of `R' code blocks.

     (org-babel-do-load-languages
      'org-babel-load-languages
      '((emacs-lisp . nil)
        (R . t)))

   It is also possible to enable support for a language by loading the
related elisp file with `require'.

     The following adds support for evaluating `clojure' code blocks.

     (require 'ob-clojure)


File: org,  Node: Header arguments,  Next: Results of evaluation,  Prev: Languages,  Up: Working With Source Code

14.8 Header arguments
=====================

Code block functionality can be configured with header arguments.  This
section provides an overview of the use of header arguments, and then
describes each header argument in detail.

* Menu:

* Using header arguments::      Different ways to set header arguments
* Specific header arguments::   List of header arguments


File: org,  Node: Using header arguments,  Next: Specific header arguments,  Prev: Header arguments,  Up: Header arguments

14.8.1 Using header arguments
-----------------------------

The values of header arguments can be set in six different ways, each
more specific (and having higher priority) than the last.

* Menu:

* System-wide header arguments::  Set global default values
* Language-specific header arguments::  Set default values by language
* Buffer-wide header arguments::  Set default values for a specific buffer
* Header arguments in Org mode properties::  Set default values for a buffer or heading
* Code block specific header arguments::  The most common way to set values
* Header arguments in function calls::  The most specific level


File: org,  Node: System-wide header arguments,  Next: Language-specific header arguments,  Prev: Using header arguments,  Up: Using header arguments

System-wide header arguments
............................

System-wide values of header arguments can be specified by customizing
the `org-babel-default-header-args' variable:

     :session    => "none"
     :results    => "replace"
     :exports    => "code"
     :cache      => "no"
     :noweb      => "no"

   For example, the following example could be used to set the default
value of `:noweb' header arguments to `yes'.  This would have the
effect of expanding `:noweb' references by default when evaluating
source code blocks.

     (setq org-babel-default-header-args
     (cons '(:noweb . "yes")
     (assq-delete-all :noweb org-babel-default-header-args)))


File: org,  Node: Language-specific header arguments,  Next: Buffer-wide header arguments,  Prev: System-wide header arguments,  Up: Using header arguments

Language-specific header arguments
..................................

Each language can define its own set of default header arguments.  See
the language-specific documentation available online at
`http://orgmode.org/worg/org-contrib/babel'.


File: org,  Node: Buffer-wide header arguments,  Next: Header arguments in Org mode properties,  Prev: Language-specific header arguments,  Up: Using header arguments

Buffer-wide header arguments
............................

Buffer-wide header arguments may be specified as properties through the
use of `#+PROPERTY:' lines placed anywhere in an Org mode file (see
*note Property syntax::).

   For example the following would set `session' to `*R*', and
`results' to `silent' for every code block in the buffer, ensuring that
all execution took place in the same session, and no results would be
inserted into the buffer.

     #+PROPERTY: session *R*
     #+PROPERTY: results silent


File: org,  Node: Header arguments in Org mode properties,  Next: Code block specific header arguments,  Prev: Buffer-wide header arguments,  Up: Using header arguments

Header arguments in Org mode properties
.......................................

Header arguments are also read from Org mode properties (see *note
Property syntax::), which can be set on a buffer-wide or per-heading
basis.  An example of setting a header argument for all code blocks in
a buffer is

     #+PROPERTY: tangle yes

   When properties are used to set default header arguments, they are
looked up with inheritance, regardless of the value of
`org-use-property-inheritance'.  In the following example the value of
the `:cache' header argument will default to `yes' in all code blocks
in the subtree rooted at the following heading:

     * outline header
     :PROPERTIES:
     :cache:    yes
     :END:

   Properties defined in this way override the properties set in
`org-babel-default-header-args'.  It is convenient to use the
`org-set-property' function bound to `C-c C-x p' to set properties in
Org mode documents.


File: org,  Node: Code block specific header arguments,  Next: Header arguments in function calls,  Prev: Header arguments in Org mode properties,  Up: Using header arguments

Code block specific header arguments
....................................

The most common way to assign values to header arguments is at the code
block level.  This can be done by listing a sequence of header
arguments and their values as part of the `#+BEGIN_SRC' line.
Properties set in this way override both the values of
`org-babel-default-header-args' and header arguments specified as
properties.  In the following example, the `:results' header argument
is set to `silent', meaning the results of execution will not be
inserted in the buffer, and the `:exports' header argument is set to
`code', meaning only the body of the code block will be preserved on
export to HTML or LaTeX.

     #+NAME: factorial
     #+BEGIN_SRC haskell :results silent :exports code :var n=0
     fac 0 = 1
     fac n = n * fac (n-1)
     #+END_SRC
   Similarly, it is possible to set header arguments for inline code
blocks

     src_haskell[:exports both]{fac 5}

   Code block header arguments can span multiple lines using
`#+HEADER:' or `#+HEADERS:' lines preceding a code block or nested
between the `#+NAME:' line and the `#+BEGIN_SRC' line of a named code
block.  

   Multi-line header arguments on an un-named code block:
      #+HEADERS: :var data1=1
      #+BEGIN_SRC emacs-lisp :var data2=2
        (message "data1:%S, data2:%S" data1 data2)
      #+END_SRC

      #+results:
      : data1:1, data2:2

   Multi-line header arguments on a named code block:
        #+NAME: named-block
        #+HEADER: :var data=2
        #+BEGIN_SRC emacs-lisp
          (message "data:%S" data)
        #+END_SRC

        #+results: named-block
        : data:2


File: org,  Node: Header arguments in function calls,  Prev: Code block specific header arguments,  Up: Using header arguments

Header arguments in function calls
..................................

At the most specific level, header arguments for "Library of Babel" or
`#+CALL:' lines can be set as shown in the two examples below.  For more
information on the structure of `#+CALL:' lines see *note Evaluating
code blocks::.

   The following will apply the `:exports results' header argument to
the evaluation of the `#+CALL:' line.
     #+CALL: factorial(n=5) :exports results

   The following will apply the `:session special' header argument to
the evaluation of the `factorial' code block.
     #+CALL: factorial[:session special](n=5)


File: org,  Node: Specific header arguments,  Prev: Using header arguments,  Up: Header arguments

14.8.2 Specific header arguments
--------------------------------

Header arguments consist of an initial colon followed by the name of the
argument in lowercase letters.  The following header arguments are
defined:

* Menu:

* var::                         Pass arguments to code blocks
* results::                     Specify the type of results and how they will
                                be collected and handled
* file::                        Specify a path for file output
* dir::                         Specify the default (possibly remote)
                                directory for code block execution
* exports::                     Export code and/or results
* tangle::                      Toggle tangling and specify file name
* mkdirp::                      Toggle creation of parent directories of target
                                files during tangling
* comments::                    Toggle insertion of comments in tangled
                                code files
* padline::                     Control insertion of padding lines in tangled
                                code files
* no-expand::                   Turn off variable assignment and noweb
                                expansion during tangling
* session::                     Preserve the state of code evaluation
* noweb::                       Toggle expansion of noweb references
* noweb-ref::                   Specify block's noweb reference resolution target
* noweb-sep::                   String used to separate noweb references
* cache::                       Avoid re-evaluating unchanged code blocks
* sep::                         Delimiter for writing tabular results outside Org
* hlines::                      Handle horizontal lines in tables
* colnames::                    Handle column names in tables
* rownames::                    Handle row names in tables
* shebang::                     Make tangled files executable
* eval::                        Limit evaluation of specific code blocks

   Additional header arguments are defined on a language-specific
basis, see *note Languages::.


File: org,  Node: var,  Next: results,  Prev: Specific header arguments,  Up: Specific header arguments

14.8.2.1 `:var'
...............

The `:var' header argument is used to pass arguments to code blocks.
The specifics of how arguments are included in a code block vary by
language; these are addressed in the language-specific documentation.
However, the syntax used to specify arguments is the same across all
languages.  In every case, variables require a default value when they
are declared.

   The values passed to arguments can either be literal values,
references, or Emacs Lisp code (see *note Emacs Lisp evaluation of
variables: var.). References include anything in the Org mode file that
takes a `#+NAME:', `#+TBLNAME:', or `#+RESULTS:' line.  This includes
tables, lists, `#+BEGIN_EXAMPLE' blocks, other code blocks, and the
results of other code blocks.

   Argument values can be indexed in a manner similar to arrays (see
*note Indexable variable values: var.).

   The following syntax is used to pass arguments to code blocks using
the `:var' header argument.

     :var name=assign

   The argument, `assign', can either be a literal value, such as a
string `"string"' or a number `9', or a reference to a table, a list, a
literal example, another code block (with or without arguments), or the
results of evaluating another code block.

   Here are examples of passing values by reference:

"table"
     an Org mode table named with either a `#+NAME:' or `#+TBLNAME:'
     line
          #+TBLNAME: example-table
          | 1 |
          | 2 |
          | 3 |
          | 4 |

          #+NAME: table-length
          #+BEGIN_SRC emacs-lisp :var table=example-table
          (length table)
          #+END_SRC

          #+results: table-length
          : 4

"list"
     a simple list named with a `#+NAME:' line (note that nesting is not
     carried through to the source code block)

          #+NAME: example-list
            - simple
              - not
              - nested
            - list

          #+BEGIN_SRC emacs-lisp :var x=example-list
            (print x)
          #+END_SRC

          #+results:
          | simple | list |

"code block without arguments"
     a code block name (from the example above), as assigned by
     `#+NAME:', optionally followed by parentheses

          #+BEGIN_SRC emacs-lisp :var length=table-length()
          (* 2 length)
          #+END_SRC

          #+results:
          : 8

"code block with arguments"
     a code block name, as assigned by `#+NAME:', followed by
     parentheses and optional arguments passed within the parentheses
     following the code block name using standard function call syntax

          #+NAME: double
          #+BEGIN_SRC emacs-lisp :var input=8
          (* 2 input)
          #+END_SRC

          #+results: double
          : 16

          #+NAME: squared
          #+BEGIN_SRC emacs-lisp :var input=double(input=1)
          (* input input)
          #+END_SRC

          #+results: squared
          : 4

"literal example"
     a literal example block named with a `#+NAME:' line

          #+NAME: literal-example
          #+BEGIN_EXAMPLE
          A literal example
          on two lines
          #+END_EXAMPLE

          #+NAME: read-literal-example
          #+BEGIN_SRC emacs-lisp :var x=literal-example
            (concatenate 'string x " for you.")
          #+END_SRC

          #+results: read-literal-example
          : A literal example
          : on two lines for you.


Alternate argument syntax
.........................

It is also possible to specify arguments in a potentially more natural
way using the `#+NAME:' line of a code block.  As in the following
example, arguments can be packed inside of parentheses, separated by
commas, following the source name.

     #+NAME: double(input=0, x=2)
     #+BEGIN_SRC emacs-lisp
     (* 2 (+ input x))
     #+END_SRC

Indexable variable values
.........................

It is possible to reference portions of variable values by "indexing"
into the variables.  Indexes are 0 based with negative values counting
back from the end.  If an index is separated by `,'s then each
subsequent section will index into the next deepest nesting or
dimension of the value.  Note that this indexing occurs _before_ other
table related header arguments like `:hlines', `:colnames' and
`:rownames' are applied.  The following example assigns the last cell
of the first row the table `example-table' to the variable `data':

     #+NAME: example-table
     | 1 | a |
     | 2 | b |
     | 3 | c |
     | 4 | d |

     #+BEGIN_SRC emacs-lisp :var data=example-table[0,-1]
       data
     #+END_SRC

     #+results:
     : a

   Ranges of variable values can be referenced using two integers
separated by a `:', in which case the entire inclusive range is
referenced.  For example the following assigns the middle three rows of
`example-table' to `data'.

     #+NAME: example-table
     | 1 | a |
     | 2 | b |
     | 3 | c |
     | 4 | d |
     | 5 | 3 |

     #+BEGIN_SRC emacs-lisp :var data=example-table[1:3]
       data
     #+END_SRC

     #+results:
     | 2 | b |
     | 3 | c |
     | 4 | d |

   Additionally, an empty index, or the single character `*', are both
interpreted to mean the entire range and as such are equivalent to
`0:-1', as shown in the following example in which the entire first
column is referenced.

     #+NAME: example-table
     | 1 | a |
     | 2 | b |
     | 3 | c |
     | 4 | d |

     #+BEGIN_SRC emacs-lisp :var data=example-table[,0]
       data
     #+END_SRC

     #+results:
     | 1 | 2 | 3 | 4 |

   It is possible to index into the results of code blocks as well as
tables.  Any number of dimensions can be indexed.  Dimensions are
separated from one another by commas, as shown in the following example.

     #+NAME: 3D
     #+BEGIN_SRC emacs-lisp
       '(((1  2  3)  (4  5  6)  (7  8  9))
         ((10 11 12) (13 14 15) (16 17 18))
         ((19 20 21) (22 23 24) (25 26 27)))
     #+END_SRC

     #+BEGIN_SRC emacs-lisp :var data=3D[1,,1]
       data
     #+END_SRC

     #+results:
     | 11 | 14 | 17 |

Emacs Lisp evaluation of variables
..................................

Emacs lisp code can be used to initialize variable values.  When a
variable value starts with `(', `[', `'' or ``' it will be evaluated as
Emacs Lisp and the result of the evaluation will be assigned as the
variable value.  The following example demonstrates use of this
evaluation to reliably pass the file-name of the Org mode buffer to a
code block--note that evaluation of header arguments is guaranteed to
take place in the original Org mode file, while there is no such
guarantee for evaluation of the code block body.

     #+BEGIN_SRC sh :var filename=(buffer-file-name) :exports both
       wc -w $filename
     #+END_SRC

   Note that values read from tables and lists will not be evaluated as
Emacs Lisp, as shown in the following example.

     #+NAME: table
     | (a b c) |

     #+HEADERS: :var data=table[0,0]
     #+BEGIN_SRC perl
       $data
     #+END_SRC

     #+results:
     : (a b c)


File: org,  Node: results,  Next: file,  Prev: var,  Up: Specific header arguments

14.8.2.2 `:results'
...................

There are three classes of `:results' header argument.  Only one option
per class may be supplied per code block.

   * collection header arguments specify how the results should be
     collected from the code block

   * type header arguments specify what type of result the code block
     will return--which has implications for how they will be inserted
     into the Org mode buffer

   * handling header arguments specify how the results of evaluating
     the code block should be handled.

Collection
..........

The following options are mutually exclusive, and specify how the
results should be collected from the code block.

   * `value' This is the default.  The result is the value of the last
     statement in the code block.  This header argument places the
     evaluation in functional mode.  Note that in some languages, e.g.,
     Python, use of this result type requires that a `return' statement
     be included in the body of the source code block.  E.g., `:results
     value'.

   * `output' The result is the collection of everything printed to
     STDOUT during the execution of the code block.  This header
     argument places the evaluation in scripting mode.  E.g., `:results
     output'.

Type
....

The following options are mutually exclusive and specify what type of
results the code block will return.  By default, results are inserted
as either a table or scalar depending on their value.

   * `table', `vector' The results should be interpreted as an Org mode
     table.  If a single value is returned, it will be converted into a
     table with one row and one column.  E.g., `:results value table'.

   * `list' The results should be interpreted as an Org mode list.  If
     a single scalar value is returned it will be converted into a list
     with only one element.

   * `scalar', `verbatim' The results should be interpreted
     literally--they will not be converted into a table.  The results
     will be inserted into the Org mode buffer as quoted text.  E.g.,
     `:results value verbatim'.

   * `file' The results will be interpreted as the path to a file, and
     will be inserted into the Org mode buffer as a file link.  E.g.,
     `:results value file'.

   * `raw', `org' The results are interpreted as raw Org mode code and
     are inserted directly into the buffer.  If the results look like a
     table they will be aligned as such by Org mode.  E.g., `:results
     value raw'.

   * `html' Results are assumed to be HTML and will be enclosed in a
     `begin_html' block.  E.g., `:results value html'.

   * `latex' Results assumed to be LaTeX and are enclosed in a
     `begin_latex' block.  E.g., `:results value latex'.

   * `code' Result are assumed to be parsable code and are enclosed in
     a code block.  E.g., `:results value code'.

   * `pp' The result is converted to pretty-printed code and is
     enclosed in a code block.  This option currently supports Emacs
     Lisp, Python, and Ruby.  E.g., `:results value pp'.

   * `wrap' The result is wrapped in a RESULTS drawer.  This can be
     useful for inserting `raw' or `org' syntax results in such a way
     that their extent is known and they can be automatically removed
     or replaced.

Handling
........

The following results options indicate what happens with the results
once they are collected.

   * `silent' The results will be echoed in the minibuffer but will not
     be inserted into the Org mode buffer.  E.g., `:results output
     silent'.

   * `replace' The default value.  Any existing results will be
     removed, and the new results will be inserted into the Org mode
     buffer in their place.  E.g., `:results output replace'.

   * `append' If there are pre-existing results of the code block then
     the new results will be appended to the existing results.
     Otherwise the new results will be inserted as with `replace'.

   * `prepend' If there are pre-existing results of the code block then
     the new results will be prepended to the existing results.
     Otherwise the new results will be inserted as with `replace'.


File: org,  Node: file,  Next: dir,  Prev: results,  Up: Specific header arguments

14.8.2.3 `:file'
................

The header argument `:file' is used to specify an external file in which
to save code block results.  After code block evaluation an Org mode
style `[[file:]]' link (see *note Link format::) to the file will be
inserted into the Org mode buffer.  Some languages including R,
gnuplot, dot, and ditaa provide special handling of the `:file' header
argument automatically wrapping the code block body in the boilerplate
code required to save output to the specified file.  This is often
useful for saving graphical output of a code block to the specified
file.

   The argument to `:file' should be either a string specifying the
path to a file, or a list of two strings in which case the first
element of the list should be the path to a file and the second a
description for the link.


File: org,  Node: dir,  Next: exports,  Prev: file,  Up: Specific header arguments

14.8.2.4 `:dir' and remote execution
....................................

While the `:file' header argument can be used to specify the path to the
output file, `:dir' specifies the default directory during code block
execution.  If it is absent, then the directory associated with the
current buffer is used.  In other words, supplying `:dir path'
temporarily has the same effect as changing the current directory with
`M-x cd path', and then not supplying `:dir'.  Under the surface,
`:dir' simply sets the value of the Emacs variable `default-directory'.

   When using `:dir', you should supply a relative path for file output
(e.g. `:file myfile.jpg' or `:file results/myfile.jpg') in which case
that path will be interpreted relative to the default directory.

   In other words, if you want your plot to go into a folder called
`Work' in your home directory, you could use

     #+BEGIN_SRC R :file myplot.png :dir ~/Work
     matplot(matrix(rnorm(100), 10), type="l")
     #+END_SRC

Remote execution
................

A directory on a remote machine can be specified using tramp file
syntax, in which case the code will be evaluated on the remote machine.
An example is

     #+BEGIN_SRC R :file plot.png :dir /dand@yakuba.princeton.edu:
     plot(1:10, main=system("hostname", intern=TRUE))
     #+END_SRC

   Text results will be returned to the local Org mode buffer as usual,
and file output will be created on the remote machine with relative
paths interpreted relative to the remote directory.  An Org mode link
to the remote file will be created.

   So, in the above example a plot will be created on the remote
machine, and a link of the following form will be inserted in the org
buffer:

     [[file:/scp:dand@yakuba.princeton.edu:/home/dand/plot.png][plot.png]]

   Most of this functionality follows immediately from the fact that
`:dir' sets the value of the Emacs variable `default-directory', thanks
to tramp.  Those using XEmacs, or GNU Emacs prior to version 23 may
need to install tramp separately in order for these features to work
correctly.

Further points
..............

   * If `:dir' is used in conjunction with `:session', although it will
     determine the starting directory for a new session as expected, no
     attempt is currently made to alter the directory associated with
     an existing session.

   * `:dir' should typically not be used to create files during export
     with `:exports results' or `:exports both'.  The reason is that,
     in order to retain portability of exported material between
     machines, during export links inserted into the buffer will _not_
     be expanded against `default directory'.  Therefore, if
     `default-directory' is altered using `:dir', it is probable that
     the file will be created in a location to which the link does not
     point.


File: org,  Node: exports,  Next: tangle,  Prev: dir,  Up: Specific header arguments

14.8.2.5 `:exports'
...................

The `:exports' header argument specifies what should be included in HTML
or LaTeX exports of the Org mode file.

   * `code' The default.  The body of code is included into the
     exported file.  E.g., `:exports code'.

   * `results' The result of evaluating the code is included in the
     exported file.  E.g., `:exports results'.

   * `both' Both the code and results are included in the exported
     file.  E.g., `:exports both'.

   * `none' Nothing is included in the exported file.  E.g., `:exports
     none'.


File: org,  Node: tangle,  Next: mkdirp,  Prev: exports,  Up: Specific header arguments

14.8.2.6 `:tangle'
..................

The `:tangle' header argument specifies whether or not the code block
should be included in tangled extraction of source code files.

   * `tangle' The code block is exported to a source code file named
     after the full path (including the directory) and file name (w/o
     extension) of the Org mode file.  E.g., `:tangle yes'.

   * `no' The default.  The code block is not exported to a source code
     file.  E.g., `:tangle no'.

   * other Any other string passed to the `:tangle' header argument is
     interpreted as a path (directory and file name relative to the
     directory of the Org mode file) to which the block will be
     exported.  E.g., `:tangle path'.


File: org,  Node: mkdirp,  Next: comments,  Prev: tangle,  Up: Specific header arguments

14.8.2.7 `:mkdirp'
..................

The `:mkdirp' header argument can be used to create parent directories
of tangled files when missing.  This can be set to `yes' to enable
directory creation or to `no' to inhibit directory creation.


File: org,  Node: comments,  Next: padline,  Prev: mkdirp,  Up: Specific header arguments

14.8.2.8 `:comments'
....................

By default code blocks are tangled to source-code files without any
insertion of comments beyond those which may already exist in the body
of the code block.  The `:comments' header argument can be set as
follows to control the insertion of extra comments into the tangled
code file.

   * `no' The default.  No extra comments are inserted during tangling.

   * `link' The code block is wrapped in comments which contain
     pointers back to the original Org file from which the code was
     tangled.

   * `yes' A synonym for "link" to maintain backwards compatibility.

   * `org' Include text from the Org mode file as a comment.

     The text is picked from the leading context of the tangled code
     and is limited by the nearest headline or source block as the case
     may be.

   * `both' Turns on both the "link" and "org" comment options.

   * `noweb' Turns on the "link" comment option, and additionally wraps
     expanded noweb references in the code block body in link comments.


File: org,  Node: padline,  Next: no-expand,  Prev: comments,  Up: Specific header arguments

14.8.2.9 `:padline'
...................

Control in insertion of padding lines around code block bodies in
tangled code files.  The default value is `yes' which results in
insertion of newlines before and after each tangled code block.  The
following arguments are accepted.

   * `yes' Insert newlines before and after each code block body in
     tangled code files.

   * `no' Do not insert any newline padding in tangled output.


File: org,  Node: no-expand,  Next: session,  Prev: padline,  Up: Specific header arguments

14.8.2.10 `:no-expand'
......................

By default, code blocks are expanded with `org-babel-expand-src-block'
during tangling.  This has the effect of assigning values to variables
specified with `:var' (see *note var::), and of replacing "noweb"
references (see *note Noweb reference syntax::) with their targets.  The
`:no-expand' header argument can be used to turn off this behavior.


File: org,  Node: session,  Next: noweb,  Prev: no-expand,  Up: Specific header arguments

14.8.2.11 `:session'
....................

The `:session' header argument starts a session for an interpreted
language where state is preserved.

   By default, a session is not started.

   A string passed to the `:session' header argument will give the
session a name.  This makes it possible to run concurrent sessions for
each interpreted language.


File: org,  Node: noweb,  Next: noweb-ref,  Prev: session,  Up: Specific header arguments

14.8.2.12 `:noweb'
..................

The `:noweb' header argument controls expansion of "noweb" style (see
*note Noweb reference syntax::) references in a code block.  This header
argument can have one of three values: `yes', `no', or `tangle'.

   * `yes' All "noweb" syntax references in the body of the code block
     will be expanded before the block is evaluated, tangled or
     exported.

   * `no' The default.  No "noweb" syntax specific action is taken when
     the code block is evaluated, tangled or exported.

   * `tangle' All "noweb" syntax references in the body of the code
     block will be expanded before the block is tangled, however
     "noweb" references will not be expanded when the block is
     evaluated or exported.

Noweb prefix lines
..................

Noweb insertions are now placed behind the line prefix of the
`<<reference>>'.  This behavior is illustrated in the following
example.  Because the `<<example>>' noweb reference appears behind the
SQL comment syntax, each line of the expanded noweb reference will be
commented.

   This code block:

     -- <<example>>

   expands to:

     -- this is the
     -- multi-line body of example

   Note that noweb replacement text that does not contain any newlines
will not be affected by this change, so it is still possible to use
inline noweb references.


File: org,  Node: noweb-ref,  Next: noweb-sep,  Prev: noweb,  Up: Specific header arguments

14.8.2.13 `:noweb-ref'
......................

When expanding "noweb" style references the bodies of all code block
with _either_ a block name matching the reference name _or_ a
`:noweb-ref' header argument matching the reference name will be
concatenated together to form the replacement text.

   By setting this header argument at the sub-tree or file level,
simple code block concatenation may be achieved.  For example, when
tangling the following Org mode file, the bodies of code blocks will be
concatenated into the resulting pure code file(1).

      #+BEGIN_SRC sh :tangle yes :noweb yes :shebang #!/bin/sh
        <<fullest-disk>>
      #+END_SRC
      * the mount point of the fullest disk
        :PROPERTIES:
        :noweb-ref: fullest-disk
        :END:

      ** query all mounted disks
      #+BEGIN_SRC sh
        df \
      #+END_SRC

      ** strip the header row
      #+BEGIN_SRC sh
        |sed '1d' \
      #+END_SRC

      ** sort by the percent full
      #+BEGIN_SRC sh
        |awk '{print $5 " " $6}'|sort -n |tail -1 \
      #+END_SRC

      ** extract the mount point
      #+BEGIN_SRC sh
        |awk '{print $2}'
      #+END_SRC

   The `:noweb-sep' (see *note noweb-sep::) header argument holds the
string used to separate accumulate noweb references like those above.
By default a newline is used.

   ---------- Footnotes ----------

   (1) (The example needs property inheritance to be turned on for the
`noweb-ref' property, see *note Property inheritance::).


File: org,  Node: noweb-sep,  Next: cache,  Prev: noweb-ref,  Up: Specific header arguments

14.8.2.14 `:noweb-sep'
......................

The `:noweb-sep' header argument holds the string used to separate
accumulate noweb references (see *note noweb-ref::).  By default a
newline is used.


File: org,  Node: cache,  Next: sep,  Prev: noweb-sep,  Up: Specific header arguments

14.8.2.15 `:cache'
..................

The `:cache' header argument controls the use of in-buffer caching of
the results of evaluating code blocks.  It can be used to avoid
re-evaluating unchanged code blocks.  Note that the `:cache' header
argument will not attempt to cache results when the `:session' header
argument is used, because the results of the code block execution may
be stored in the session outside of the Org-mode buffer.  The `:cache'
header argument can have one of two values: `yes' or `no'.

   * `no' The default.  No caching takes place, and the code block will
     be evaluated every time it is called.

   * `yes' Every time the code block is run a SHA1 hash of the code and
     arguments passed to the block will be generated.  This hash is
     packed into the `#+results:' line and will be checked on subsequent
     executions of the code block.  If the code block has not changed
     since the last time it was evaluated, it will not be re-evaluated.

   Code block caches notice if the value of a variable argument to the
code block has changed.  If this is the case, the cache is invalidated
and the code block is re-run.  In the following example, `caller' will
not be re-run unless the results of `random' have changed since it was
last run.

      #+NAME: random
      #+BEGIN_SRC R :cache yes
      runif(1)
      #+END_SRC

      #+results[a2a72cd647ad44515fab62e144796432793d68e1]: random
      0.4659510825295

      #+NAME: caller
      #+BEGIN_SRC emacs-lisp :var x=random :cache yes
      x
      #+END_SRC

      #+results[bec9c8724e397d5df3b696502df3ed7892fc4f5f]: caller
      0.254227238707244


File: org,  Node: sep,  Next: hlines,  Prev: cache,  Up: Specific header arguments

14.8.2.16 `:sep'
................

The `:sep' header argument can be used to control the delimiter used
when writing tabular results out to files external to Org mode.  This
is used either when opening tabular results of a code block by calling
the `org-open-at-point' function bound to `C-c C-o' on the code block,
or when writing code block results to an external file (see *note
file::) header argument.

   By default, when `:sep' is not specified output tables are tab
delimited.


File: org,  Node: hlines,  Next: colnames,  Prev: sep,  Up: Specific header arguments

14.8.2.17 `:hlines'
...................

Tables are frequently represented with one or more horizontal lines, or
hlines.  The `:hlines' argument to a code block accepts the values
`yes' or `no', with a default value of `no'.

   * `no' Strips horizontal lines from the input table.  In most
     languages this is the desired effect because an `hline' symbol is
     interpreted as an unbound variable and raises an error.  Setting
     `:hlines no' or relying on the default value yields the following
     results.

          #+TBLNAME: many-cols
          | a | b | c |
          |---+---+---|
          | d | e | f |
          |---+---+---|
          | g | h | i |

          #+NAME: echo-table
          #+BEGIN_SRC python :var tab=many-cols
            return tab
          #+END_SRC

          #+results: echo-table
          | a | b | c |
          | d | e | f |
          | g | h | i |

   * `yes' Leaves hlines in the table.  Setting `:hlines yes' has this
     effect.

          #+TBLNAME: many-cols
          | a | b | c |
          |---+---+---|
          | d | e | f |
          |---+---+---|
          | g | h | i |

          #+NAME: echo-table
          #+BEGIN_SRC python :var tab=many-cols :hlines yes
            return tab
          #+END_SRC

          #+results: echo-table
          | a | b | c |
          |---+---+---|
          | d | e | f |
          |---+---+---|
          | g | h | i |


File: org,  Node: colnames,  Next: rownames,  Prev: hlines,  Up: Specific header arguments

14.8.2.18 `:colnames'
.....................

The `:colnames' header argument accepts the values `yes', `no', or
`nil' for unassigned.  The default value is `nil'.  Note that the
behavior of the `:colnames' header argument may differ across
languages.  For example Emacs Lisp code blocks ignore the `:colnames'
header argument entirely given the ease with which tables with column
names may be handled directly in Emacs Lisp.

   * `nil' If an input table looks like it has column names (because
     its second row is an hline), then the column names will be removed
     from the table before processing, then reapplied to the results.

          #+TBLNAME: less-cols
          | a |
          |---|
          | b |
          | c |

          #+NAME: echo-table-again
          #+BEGIN_SRC python :var tab=less-cols
            return [[val + '*' for val in row] for row in tab]
          #+END_SRC

          #+results: echo-table-again
          | a  |
          |----|
          | b* |
          | c* |

     Please note that column names are not removed before the table is
     indexed using variable indexing *Note Indexable variable values:
     var.

   * `no' No column name pre-processing takes place

   * `yes' Column names are removed and reapplied as with `nil' even if
     the table does not "look like" it has column names (i.e. the
     second row is not an hline)


File: org,  Node: rownames,  Next: shebang,  Prev: colnames,  Up: Specific header arguments

14.8.2.19 `:rownames'
.....................

The `:rownames' header argument can take on the values `yes' or `no',
with a default value of `no'.

   * `no' No row name pre-processing will take place.

   * `yes' The first column of the table is removed from the table
     before processing, and is then reapplied to the results.

          #+TBLNAME: with-rownames
          | one | 1 | 2 | 3 | 4 |  5 |
          | two | 6 | 7 | 8 | 9 | 10 |

          #+NAME: echo-table-once-again
          #+BEGIN_SRC python :var tab=with-rownames :rownames yes
            return [[val + 10 for val in row] for row in tab]
          #+END_SRC

          #+results: echo-table-once-again
          | one | 11 | 12 | 13 | 14 | 15 |
          | two | 16 | 17 | 18 | 19 | 20 |

     Please note that row names are not removed before the table is
     indexed using variable indexing *Note Indexable variable values:
     var.



File: org,  Node: shebang,  Next: eval,  Prev: rownames,  Up: Specific header arguments

14.8.2.20 `:shebang'
....................

Setting the `:shebang' header argument to a string value (e.g.
`:shebang "#!/bin/bash"') causes the string to be inserted as the first
line of any tangled file holding the code block, and the file
permissions of the tangled file are set to make it executable.


File: org,  Node: eval,  Prev: shebang,  Up: Specific header arguments

14.8.2.21 `:eval'
.................

The `:eval' header argument can be used to limit the evaluation of
specific code blocks.  The `:eval' header argument can be useful for
protecting against the evaluation of dangerous code blocks or to ensure
that evaluation will require a query regardless of the value of the
`org-confirm-babel-evaluate' variable.  The possible values of `:eval'
and their effects are shown below.

`never or no'
     The code block will not be evaluated under any circumstances.

`query'
     Evaluation of the code block will require a query.

`never-export or no-export'
     The code block will not be evaluated during export but may still
     be called interactively.

`query-export'
     Evaluation of the code block during export will require a query.

   If this header argument is not set then evaluation is determined by
the value of the `org-confirm-babel-evaluate' variable see *note Code
evaluation security::.


File: org,  Node: Results of evaluation,  Next: Noweb reference syntax,  Prev: Header arguments,  Up: Working With Source Code

14.9 Results of evaluation
==========================

The way in which results are handled depends on whether a session is
invoked, as well as on whether `:results value' or `:results output' is
used.  The following table shows the table possibilities.  For a full
listing of the possible results header arguments see *note results::.

                    Non-session              Session
`:results value'    value of last            value of last expression
                    expression               
`:results output'   contents of STDOUT       concatenation of interpreter
                                             output

   Note: With `:results value', the result in both `:session' and
non-session is returned to Org mode as a table (a one- or
two-dimensional vector of strings or numbers) when appropriate.

14.9.1 Non-session
------------------

14.9.1.1 `:results value'
.........................

This is the default.  Internally, the value is obtained by wrapping the
code in a function definition in the external language, and evaluating
that function.  Therefore, code should be written as if it were the
body of such a function.  In particular, note that Python does not
automatically return a value from a function unless a `return'
statement is present, and so a `return' statement will usually be
required in Python.

   This is the only one of the four evaluation contexts in which the
code is automatically wrapped in a function definition.

14.9.1.2 `:results output'
..........................

The code is passed to the interpreter as an external process, and the
contents of the standard output stream are returned as text.  (In
certain languages this also contains the error output stream; this is
an area for future work.)

14.9.2 Session
--------------

14.9.2.1 `:results value'
.........................

The code is passed to an interpreter running as an interactive Emacs
inferior process.  Only languages which provide tools for interactive
evaluation of code have session support, so some language (e.g., C and
ditaa) do not support the `:session' header argument, and in other
languages (e.g., Python and Haskell) which have limitations on the code
which may be entered into interactive sessions, those limitations apply
to the code in code blocks using the `:session' header argument as well.

   Unless the `:results output' option is supplied (see below) the
result returned is the result of the last evaluation performed by the
interpreter.  (This is obtained in a language-specific manner: the
value of the variable `_' in Python and Ruby, and the value of
`.Last.value' in R).

14.9.2.2 `:results output'
..........................

The code is passed to the interpreter running as an interactive Emacs
inferior process.  The result returned is the concatenation of the
sequence of (text) output from the interactive interpreter.  Notice
that this is not necessarily the same as what would be sent to `STDOUT'
if the same code were passed to a non-interactive interpreter running
as an external process.  For example, compare the following two blocks:

     #+BEGIN_SRC python :results output
      print "hello"
      2
      print "bye"
     #+END_SRC

     #+results:
     : hello
     : bye

   In non-session mode, the `2' is not printed and does not appear.
     #+BEGIN_SRC python :results output :session
      print "hello"
      2
      print "bye"
     #+END_SRC

     #+results:
     : hello
     : 2
     : bye

   But in `:session' mode, the interactive interpreter receives input
`2' and prints out its value, `2'.  (Indeed, the other print statements
are unnecessary here).


File: org,  Node: Noweb reference syntax,  Next: Key bindings and useful functions,  Prev: Results of evaluation,  Up: Working With Source Code

14.10 Noweb reference syntax
============================

The "noweb" (see `http://www.cs.tufts.edu/~nr/noweb/') Literate
Programming system allows named blocks of code to be referenced by
using the familiar Noweb syntax:

     <<code-block-name>>

   When a code block is tangled or evaluated, whether or not "noweb"
references are expanded depends upon the value of the `:noweb' header
argument.  If `:noweb yes', then a Noweb reference is expanded before
evaluation.  If `:noweb no', the default, then the reference is not
expanded before evaluation.  See the *note noweb-ref:: header argument
for a more flexible way to resolve noweb references.

   It is possible to include the _results_ of a code block rather than
the body.  This is done by appending parenthesis to the code block name
which may optionally contain arguments to the code block as shown below.

     <<code-block-name(optional arguments)>>

   Note: the default value, `:noweb no', was chosen to ensure that
correct code is not broken in a language, such as Ruby, where `<<arg>>'
is a syntactically valid construct.  If `<<arg>>' is not syntactically
valid in languages that you use, then please consider setting the
default value.

   Note: if noweb tangling is slow in large Org-mode files consider
setting the `*org-babel-use-quick-and-dirty-noweb-expansion*' variable
to true.  This will result in faster noweb reference resolution at the
expense of not correctly resolving inherited values of the `:noweb-ref'
header argument.


File: org,  Node: Key bindings and useful functions,  Next: Batch execution,  Prev: Noweb reference syntax,  Up: Working With Source Code

14.11 Key bindings and useful functions
=======================================

Many common Org mode key sequences are re-bound depending on the
context.

   Within a code block, the following key bindings are active:

`C-c C-c'          `org-babel-execute-src-block'
`C-c C-o'          `org-babel-open-src-block-result'
`C-<up>'           `org-babel-load-in-session'
`M-<down>'         `org-babel-pop-to-session'

   In an Org mode buffer, the following key bindings are active:

`C-c C-v p'   or   `C-c C-v      `org-babel-previous-src-block'
C-p'                             
`C-c C-v n'   or   `C-c C-v      `org-babel-next-src-block'
C-n'                             
`C-c C-v e'   or   `C-c C-v      `org-babel-execute-maybe'
C-e'                             
`C-c C-v o'   or   `C-c C-v      `org-babel-open-src-block-result'
C-o'                             
`C-c C-v v'   or   `C-c C-v      `org-babel-expand-src-block'
C-v'                             
`C-c C-v u'   or   `C-c C-v      `org-babel-goto-src-block-head'
C-u'                             
`C-c C-v g'   or   `C-c C-v      `org-babel-goto-named-src-block'
C-g'                             
`C-c C-v r'   or   `C-c C-v      `org-babel-goto-named-result'
C-r'                             
`C-c C-v b'   or   `C-c C-v      `org-babel-execute-buffer'
C-b'                             
`C-c C-v s'   or   `C-c C-v      `org-babel-execute-subtree'
C-s'                             
`C-c C-v d'   or   `C-c C-v      `org-babel-demarcate-block'
C-d'                             
`C-c C-v t'   or   `C-c C-v      `org-babel-tangle'
C-t'                             
`C-c C-v f'   or   `C-c C-v      `org-babel-tangle-file'
C-f'                             
`C-c C-v c'   or   `C-c C-v      `org-babel-check-src-block'
C-c'                             
`C-c C-v j'   or   `C-c C-v      `org-babel-insert-header-arg'
C-j'                             
`C-c C-v l'   or   `C-c C-v      `org-babel-load-in-session'
C-l'                             
`C-c C-v i'   or   `C-c C-v      `org-babel-lob-ingest'
C-i'                             
`C-c C-v I'   or   `C-c C-v      `org-babel-view-src-block-info'
C-I'                             
`C-c C-v z'   or   `C-c C-v      `org-babel-switch-to-session-with-code'
C-z'                             
`C-c C-v a'   or   `C-c C-v      `org-babel-sha1-hash'
C-a'                             
`C-c C-v h'   or   `C-c C-v      `org-babel-describe-bindings'
C-h'                             
`C-c C-v x'   or   `C-c C-v      `org-babel-do-key-sequence-in-edit-buffer'
C-x'                             


File: org,  Node: Batch execution,  Prev: Key bindings and useful functions,  Up: Working With Source Code

14.12 Batch execution
=====================

It is possible to call functions from the command line.  This shell
script calls `org-babel-tangle' on every one of its arguments.

   Be sure to adjust the paths to fit your system.

     #!/bin/sh
     # -*- mode: shell-script -*-
     #
     # tangle files with org-mode
     #
     DIR=`pwd`
     FILES=""
     ORGINSTALL="~/src/org/lisp/org-install.el"

     # wrap each argument in the code required to call tangle on it
     for i in $@; do
         FILES="$FILES \"$i\""
     done

     emacs -Q --batch -l $ORGINSTALL \
     --eval "(progn
     (add-to-list 'load-path (expand-file-name \"~/src/org/lisp/\"))
     (add-to-list 'load-path (expand-file-name \"~/src/org/contrib/lisp/\"))
     (require 'org)(require 'org-exp)(require 'ob)(require 'ob-tangle)
     (mapc (lambda (file)
            (find-file (expand-file-name file \"$DIR\"))
            (org-babel-tangle)
            (kill-buffer)) '($FILES)))" 2>&1 |grep tangled


File: org,  Node: Miscellaneous,  Next: Hacking,  Prev: Working With Source Code,  Up: Top

15 Miscellaneous
****************

* Menu:

* Completion::                  M-TAB knows what you need
* Easy Templates::              Quick insertion of structural elements
* Speed keys::                  Electric commands at the beginning of a headline
* Code evaluation security::    Org mode files evaluate inline code
* Customization::               Adapting Org to your taste
* In-buffer settings::          Overview of the #+KEYWORDS
* The very busy C-c C-c key::   When in doubt, press C-c C-c
* Clean view::                  Getting rid of leading stars in the outline
* TTY keys::                    Using Org on a tty
* Interaction::                 Other Emacs packages
* org-crypt.el::                Encrypting Org files


File: org,  Node: Completion,  Next: Easy Templates,  Prev: Miscellaneous,  Up: Miscellaneous

15.1 Completion
===============

Emacs would not be Emacs without completion, and Org mode uses it
whenever it makes sense.  If you prefer an iswitchb- or ido-like
interface for some of the completion prompts, you can specify your
preference by setting at most one of the variables
`org-completion-use-iswitchb' `org-completion-use-ido'.

   Org supports in-buffer completion.  This type of completion does not
make use of the minibuffer.  You simply type a few letters into the
buffer and use the key to complete text right there.

`M-<TAB>'
     Complete word at point
        * At the beginning of a headline, complete TODO keywords.

        * After `\', complete TeX symbols supported by the exporter.

        * After `*', complete headlines in the current buffer so that
          they can be used in search links like `[[*find this
          headline]]'.

        * After `:' in a headline, complete tags.  The list of tags is
          taken from the variable `org-tag-alist' (possibly set through
          the `#+TAGS' in-buffer option, *note Setting tags::), or it
          is created dynamically from all tags used in the current
          buffer.

        * After `:' and not in a headline, complete property keys.  The
          list of keys is constructed dynamically from all keys used in
          the current buffer.

        * After `[', complete link abbreviations (*note Link
          abbreviations::).

        * After `#+', complete the special keywords like `TYP_TODO' or
          `OPTIONS' which set file-specific options for Org mode.  When
          the option keyword is already complete, pressing `M-<TAB>'
          again will insert example settings for this keyword.

        * In the line after `#+STARTUP: ', complete startup keywords,
          i.e. valid keys for this line.

        * Elsewhere, complete dictionary words using Ispell.


File: org,  Node: Easy Templates,  Next: Speed keys,  Prev: Completion,  Up: Miscellaneous

15.2 Easy Templates
===================

Org mode supports insertion of empty structural elements (like
`#+BEGIN_SRC' and `#+END_SRC' pairs) with just a few key strokes.  This
is achieved through a native template expansion mechanism.  Note that
Emacs has several other template mechanisms which could be used in a
similar way, for example `yasnippet'.

   To insert a structural element, type a `<', followed by a template
selector and `<TAB>'.  Completion takes effect only when the above
keystrokes are typed on a line by itself.

   The following template selectors are currently supported.

`s'     `#+begin_src     ... #+end_src'
`e'     `#+begin_example ... #+end_example'
`q'     `#+begin_quote   ... #+end_quote'
`v'     `#+begin_verse   ... #+end_verse'
`c'     `#+begin_center  ... #+end_center'
`l'     `#+begin_latex   ... #+end_latex'
`L'     `#+latex:'
`h'     `#+begin_html    ... #+end_html'
`H'     `#+html:'
`a'     `#+begin_ascii   ... #+end_ascii'
`A'     `#+ascii:'
`i'     `#+index:' line
`I'     `#+include:' line

   For example, on an empty line, typing "<e" and then pressing TAB,
will expand into a complete EXAMPLE template.

   You can install additional templates by customizing the variable
`org-structure-template-alist'.  See the docstring of the variable for
additional details.


File: org,  Node: Speed keys,  Next: Code evaluation security,  Prev: Easy Templates,  Up: Miscellaneous

15.3 Speed keys
===============

Single keys can be made to execute commands when the cursor is at the
beginning of a headline, i.e. before the first star.  Configure the
variable `org-use-speed-commands' to activate this feature.  There is a
pre-defined list of commands, and you can add more such commands using
the variable `org-speed-commands-user'.  Speed keys do not only speed up
navigation and other commands, but they also provide an alternative way
to execute commands bound to keys that are not or not easily available
on a TTY, or on a small mobile device with a limited keyboard.

   To see which commands are available, activate the feature and press
`?' with the cursor at the beginning of a headline.


File: org,  Node: Code evaluation security,  Next: Customization,  Prev: Speed keys,  Up: Miscellaneous

15.4 Code evaluation and security issues
========================================

Org provides tools to work with the code snippets, including evaluating
them.

   Running code on your machine always comes with a security risk.
Badly written or malicious code can be executed on purpose or by
accident.  Org has default settings which will only evaluate such code
if you give explicit permission to do so, and as a casual user of these
features you should leave these precautions intact.

   For people who regularly work with such code, the confirmation
prompts can become annoying, and you might want to turn them off.  This
can be done, but you must be aware of the risks that are involved.

   Code evaluation can happen under the following circumstances:

Source code blocks
     Source code blocks can be evaluated during export, or when
     pressing `C-c C-c' in the block.  The most important thing to
     realize here is that Org mode files which contain code snippets
     are, in a certain sense, like executable files.  So you should
     accept them and load them into Emacs only from trusted
     sources--just like you would do with a program you install on your
     computer.

     Make sure you know what you are doing before customizing the
     variables which take off the default security brakes.

      -- User Option: org-confirm-babel-evaluate
          When t (the default), the user is asked before every code
          block evaluation.  When nil, the user is not asked.  When set
          to a function, it is called with two arguments (language and
          body of the code block) and should return t to ask and nil
          not to ask.

     For example, here is how to execute "ditaa" code (which is
     considered safe) without asking:
          (defun my-org-confirm-babel-evaluate (lang body)
            (not (string= lang "ditaa")))  ; don't ask for ditaa
          (setq org-confirm-babel-evaluate 'my-org-confirm-babel-evaluate)

Following `shell' and `elisp' links
     Org has two link types that can directly evaluate code (*note
     External links::).  These links can be problematic because the
     code to be evaluated is not visible.

      -- User Option: org-confirm-shell-link-function
          Function to queries user about shell link execution.

      -- User Option: org-confirm-elisp-link-function
          Functions to query user for Emacs Lisp link execution.

Formulas in tables
     Formulas in tables (*note The spreadsheet::) are code that is
     evaluated either by the calc interpreter, or by the Emacs Lisp
     interpreter.


File: org,  Node: Customization,  Next: In-buffer settings,  Prev: Code evaluation security,  Up: Miscellaneous

15.5 Customization
==================

There are more than 180 variables that can be used to customize Org.
For the sake of compactness of the manual, I am not describing the
variables here.  A structured overview of customization variables is
available with `M-x org-customize'.  Or select `Browse Org Group' from
the `Org->Customization' menu.  Many settings can also be activated on
a per-file basis, by putting special lines into the buffer (*note
In-buffer settings::).


File: org,  Node: In-buffer settings,  Next: The very busy C-c C-c key,  Prev: Customization,  Up: Miscellaneous

15.6 Summary of in-buffer settings
==================================

Org mode uses special lines in the buffer to define settings on a
per-file basis.  These lines start with a `#+' followed by a keyword, a
colon, and then individual words defining a setting.  Several setting
words can be in the same line, but you can also have multiple lines for
the keyword.  While these settings are described throughout the manual,
here is a summary.  After changing any of those lines in the buffer,
press `C-c C-c' with the cursor still in the line to activate the
changes immediately.  Otherwise they become effective only when the
file is visited again in a new Emacs session.

`#+ARCHIVE: %s_done::'
     This line sets the archive location for the agenda file.  It
     applies for all subsequent lines until the next `#+ARCHIVE' line,
     or the end of the file.  The first such line also applies to any
     entries before it.  The corresponding variable is
     `org-archive-location'.

`#+CATEGORY:'
     This line sets the category for the agenda file.  The category
     applies for all subsequent lines until the next `#+CATEGORY' line,
     or the end of the file.  The first such line also applies to any
     entries before it.

`#+COLUMNS: %25ITEM .....'
     Set the default format for columns view.  This format applies when
     columns view is invoked in locations where no `COLUMNS' property
     applies.

`#+CONSTANTS: name1=value1 ...'
     Set file-local values for constants to be used in table formulas.
     This line sets the local variable
     `org-table-formula-constants-local'.  The global version of this
     variable is `org-table-formula-constants'.

`#+FILETAGS: :tag1:tag2:tag3:'
     Set tags that can be inherited by any entry in the file, including
     the top-level entries.

`#+DRAWERS: NAME1 .....'
     Set the file-local set of drawers.  The corresponding global
     variable is `org-drawers'.

`#+LINK:  linkword replace'
     These lines (several are allowed) specify link abbreviations.
     *Note Link abbreviations::.  The corresponding variable is
     `org-link-abbrev-alist'.

`#+PRIORITIES: highest lowest default'
     This line sets the limits and the default for the priorities.  All
     three must be either letters A-Z or numbers 0-9.  The highest
     priority must have a lower ASCII number than the lowest priority.

`#+PROPERTY: Property_Name Value'
     This line sets a default inheritance value for entries in the
     current buffer, most useful for specifying the allowed values of a
     property.  

`#+SETUPFILE: file'
     This line defines a file that holds more in-buffer setup.
     Normally this is entirely ignored.  Only when the buffer is parsed
     for option-setting lines (i.e. when starting Org mode for a file,
     when pressing `C-c C-c' in a settings line, or when exporting),
     then the contents of this file are parsed as if they had been
     included in the buffer.  In particular, the file can be any other
     Org mode file with internal setup.  You can visit the file the
     cursor is in the line with `C-c ''.

`#+STARTUP:'
     This line sets options to be used at startup of Org mode, when an
     Org file is being visited.

     The first set of options deals with the initial visibility of the
     outline tree.  The corresponding variable for global default
     settings is `org-startup-folded', with a default value `t', which
     means `overview'.  
          overview         top-level headlines only
          content          all headlines
          showall          no folding of any entries
          showeverything   show even drawer contents

     Dynamic virtual indentation is controlled by the variable
     `org-startup-indented'(1)
          indent     start with `org-indent-mode' turned on
          noindent   start with `org-indent-mode' turned off

     Then there are options for aligning tables upon visiting a file.
     This is useful in files containing narrowed table columns.  The
     corresponding variable is `org-startup-align-all-tables', with a
     default value `nil'.  
          align      align all tables
          noalign    don't align tables on startup

     When visiting a file, inline images can be automatically
     displayed.  The corresponding variable is
     `org-startup-with-inline-images', with a default value `nil' to
     avoid delays when visiting a file.  
          inlineimages   show inline images
          noinlineimages don't show inline images on startup

     Logging the closing and reopening of TODO items and clock
     intervals can be configured using these options (see variables
     `org-log-done', `org-log-note-clock-out' and `org-log-repeat') 
          logdone            record a timestamp when an item is marked DONE
          lognotedone        record timestamp and a note when DONE
          nologdone          don't record when items are marked DONE
          logrepeat          record a time when reinstating a repeating item
          lognoterepeat      record a note when reinstating a repeating item
          nologrepeat        do not record when reinstating repeating item
          lognoteclock-out   record a note when clocking out
          nolognoteclock-out don't record a note when clocking out
          logreschedule      record a timestamp when scheduling time changes
          lognotereschedule  record a note when scheduling time changes
          nologreschedule    do not record when a scheduling date changes
          logredeadline      record a timestamp when deadline changes
          lognoteredeadline  record a note when deadline changes
          nologredeadline    do not record when a deadline date changes
          logrefile          record a timestamp when refiling
          lognoterefile      record a note when refiling
          nologrefile        do not record when refiling
     Here are the options for hiding leading stars in outline headings,
     and for indenting outlines.  The corresponding variables are
     `org-hide-leading-stars' and `org-odd-levels-only', both with a
     default setting `nil' (meaning `showstars' and `oddeven').  
          hidestars  make all but one of the stars starting a headline invisible.
          showstars  show all stars starting a headline
          indent     virtual indentation according to outline level
          noindent   no virtual indentation according to outline level
          odd        allow only odd outline levels (1,3,...)
          oddeven    allow all outline levels
     To turn on custom format overlays over timestamps (variables
     `org-put-time-stamp-overlays' and
     `org-time-stamp-overlay-formats'), use 
          customtime overlay custom time format
     The following options influence the table spreadsheet (variable
     `constants-unit-system').  
          constcgs   `constants.el' should use the c-g-s unit system
          constSI    `constants.el' should use the SI unit system
     To influence footnote settings, use the following keywords.  The
     corresponding variables are `org-footnote-define-inline',
     `org-footnote-auto-label', and `org-footnote-auto-adjust'.  
          fninline    define footnotes inline
          fnnoinline  define footnotes in separate section
          fnlocal     define footnotes near first reference, but not inline
          fnprompt    prompt for footnote labels
          fnauto      create `[fn:1]'-like labels automatically (default)
          fnconfirm   offer automatic label for editing or confirmation
          fnplain     create `[1]'-like labels automatically
          fnadjust    automatically renumber and sort footnotes
          nofnadjust  do not renumber and sort automatically
     To hide blocks on startup, use these keywords.  The corresponding
     variable is `org-hide-block-startup'.  
          hideblocks   Hide all begin/end blocks on startup
          nohideblocks Do not hide blocks on startup
     The display of entities as UTF-8 characters is governed by the
     variable `org-pretty-entities' and the keywords 
          entitiespretty  Show entities as UTF-8 characters where possible
          entitiesplain   Leave entities plain

`#+TAGS:  TAG1(c1) TAG2(c2)'
     These lines (several such lines are allowed) specify the valid
     tags in this file, and (potentially) the corresponding _fast tag
     selection_ keys.  The corresponding variable is `org-tag-alist'.

`#+TBLFM:'
     This line contains the formulas for the table directly above the
     line.

`#+TITLE:, #+AUTHOR:, #+EMAIL:, #+LANGUAGE:, #+TEXT:, #+DATE:,'
`#+OPTIONS:, #+BIND:, #+XSLT:,'
`#+DESCRIPTION:, #+KEYWORDS:,'
`#+LATEX_HEADER:, #+STYLE:, #+LINK_UP:, #+LINK_HOME:,'
`#+EXPORT_SELECT_TAGS:, #+EXPORT_EXCLUDE_TAGS:'
     These lines provide settings for exporting files.  For more
     details see *note Export options::.

`#+TODO:    #+SEQ_TODO:   #+TYP_TODO:'
     These lines set the TODO keywords and their interpretation in the
     current file.  The corresponding variable is `org-todo-keywords'.

   ---------- Footnotes ----------

   (1) Emacs 23 and Org mode 6.29 are required


File: org,  Node: The very busy C-c C-c key,  Next: Clean view,  Prev: In-buffer settings,  Up: Miscellaneous

15.7 The very busy C-c C-c key
==============================

The key `C-c C-c' has many purposes in Org, which are all mentioned
scattered throughout this manual.  One specific function of this key is
to add _tags_ to a headline (*note Tags::).  In many other
circumstances it means something like _"Hey Org, look here and update
according to what you see here"_.  Here is a summary of what this means
in different contexts.

   - If there are highlights in the buffer from the creation of a sparse
     tree, or from clock display, remove these highlights.

   - If the cursor is in one of the special `#+KEYWORD' lines, this
     triggers scanning the buffer for these lines and updating the
     information.

   - If the cursor is inside a table, realign the table.  This command
     works even if the automatic table editor has been turned off.

   - If the cursor is on a `#+TBLFM' line, re-apply the formulas to the
     entire table.

   - If the current buffer is a capture buffer, close the note and file
     it.  With a prefix argument, file it, without further interaction,
     to the default location.

   - If the cursor is on a `<<<target>>>', update radio targets and
     corresponding links in this buffer.

   - If the cursor is in a property line or at the start or end of a
     property drawer, offer property commands.

   - If the cursor is at a footnote reference, go to the corresponding
     definition, and vice versa.

   - If the cursor is on a statistics cookie, update it.

   - If the cursor is in a plain list item with a checkbox, toggle the
     status of the checkbox.

   - If the cursor is on a numbered item in a plain list, renumber the
     ordered list.

   - If the cursor is on the `#+BEGIN' line of a dynamic block, the
     block is updated.

   - If the cursor is at a timestamp, fix the day name in the timestamp.


File: org,  Node: Clean view,  Next: TTY keys,  Prev: The very busy C-c C-c key,  Up: Miscellaneous

15.8 A cleaner outline view
===========================

Some people find it noisy and distracting that the Org headlines start
with a potentially large number of stars, and that text below the
headlines is not indented.  While this is no problem when writing a
_book-like_ document where the outline headings are really section
headings, in a more _list-oriented_ outline, indented structure is a
lot cleaner:

     * Top level headline             |    * Top level headline
     ** Second level                  |      * Second level
     *** 3rd level                    |        * 3rd level
     some text                        |          some text
     *** 3rd level                    |        * 3rd level
     more text                        |          more text
     * Another top level headline     |    * Another top level headline

If you are using at least Emacs 23.2(1) and version 6.29 of Org, this
kind of view can be achieved dynamically at display time using
`org-indent-mode'.  In this minor mode, all lines are prefixed for
display with the necessary amount of space(2).  Also headlines are
prefixed with additional stars, so that the amount of indentation
shifts by two(3)  spaces per level.  All headline stars but the last
one are made invisible using the `org-hide' face(4) - see below under
`2.' for more information on how this works.  You can turn on
`org-indent-mode' for all files by customizing the variable
`org-startup-indented', or you can turn it on for individual files using

     #+STARTUP: indent

   If you want a similar effect in an earlier version of Emacs and/or
Org, or if you want the indentation to be hard space characters so that
the plain text file looks as similar as possible to the Emacs display,
Org supports you in the following way:

  1. _Indentation of text below headlines_
     You may indent text below each headline to make the left boundary
     line up with the headline, like

          *** 3rd level
              more text, now indented

     Org supports this with paragraph filling, line wrapping, and
     structure editing(5), preserving or adapting the indentation as
     appropriate.

  2. _Hiding leading stars_
     You can modify the display in such a way that all leading stars
     become invisible.  To do this in a global way, configure the
     variable `org-hide-leading-stars' or change this on a per-file
     basis with

          #+STARTUP: hidestars
          #+STARTUP: showstars

     With hidden stars, the tree becomes:

          * Top level headline
           * Second level
            * 3rd level
            ...

     The leading stars are not truly replaced by whitespace, they are
     only fontified with the face `org-hide' that uses the background
     color as font color.  If you are not using either white or black
     background, you may have to customize this face to get the wanted
     effect.  Another possibility is to set this font such that the
     extra stars are almost invisible, for example using the color
     `grey90' on a white background.

  3. Things become cleaner still if you skip all the even levels and
     use only odd levels 1, 3, 5..., effectively adding two stars to go
     from one outline level to the next(6).  In this way we get the
     outline view shown at the beginning of this section.  In order to
     make the structure editing and export commands handle this
     convention correctly, configure the variable
     `org-odd-levels-only', or set this on a per-file basis with one of
     the following lines:

          #+STARTUP: odd
          #+STARTUP: oddeven

     You can convert an Org file from single-star-per-level to the
     double-star-per-level convention with `M-x
     org-convert-to-odd-levels RET' in that file.  The reverse
     operation is `M-x org-convert-to-oddeven-levels'.

   ---------- Footnotes ----------

   (1) Emacs 23.1 can actually crash with `org-indent-mode'

   (2) `org-indent-mode' also sets the `wrap-prefix' property, such
that `visual-line-mode' (or purely setting `word-wrap') wraps long
lines (including headlines) correctly indented.

   (3) See the variable `org-indent-indentation-per-level'.

   (4) Turning on `org-indent-mode' sets `org-hide-leading-stars' to
`t' and `org-adapt-indentation' to `nil'.

   (5) See also the variable `org-adapt-indentation'.

   (6) When you need to specify a level for a property search or refile
targets, `LEVEL=2' will correspond to 3 stars, etc.


File: org,  Node: TTY keys,  Next: Interaction,  Prev: Clean view,  Up: Miscellaneous

15.9 Using Org on a tty
=======================

Because Org contains a large number of commands, by default many of
Org's core commands are bound to keys that are generally not accessible
on a tty, such as the cursor keys (<left>, <right>, <up>, <down>),
<TAB> and <RET>, in particular when used together with modifiers like
<Meta> and/or <Shift>.  To access these commands on a tty when special
keys are unavailable, the following alternative bindings can be used.
The tty bindings below will likely be more cumbersome; you may find for
some of the bindings below that a customized workaround suits you
better.  For example, changing a timestamp is really only fun with
`S-<cursor>' keys, whereas on a tty you would rather use `C-c .' to
re-insert the timestamp.

Default     Alternative 1  Speed   Alternative 2
                           key     
`S-<TAB>'   `C-u <TAB>'    `C'     
`M-<left>'  `C-c C-x l'    `l'     `<Esc> <left>'
`M-S-<left>'`C-c C-x L'    `L'     
`M-<right>' `C-c C-x r'    `r'     `<Esc>
                                   <right>'
`M-S-<right>'`C-c C-x R'    `R'     
`M-<up>'    `C-c C-x u'    ` '     `<Esc> <up>'
`M-S-<up>'  `C-c C-x U'    `U'     
`M-<down>'  `C-c C-x d'    ` '     `<Esc> <down>'
`M-S-<down>'`C-c C-x D'    `D'     
`S-<RET>'   `C-c C-x c'    ` '     
`M-<RET>'   `C-c C-x m'    ` '     `<Esc> <RET>'
`M-S-<RET>' `C-c C-x M'    ` '     
`S-<left>'  `C-c <left>'   ` '     
`S-<right>' `C-c <right>'  ` '     
`S-<up>'    `C-c <up>'     ` '     
`S-<down>'  `C-c <down>'   ` '     
`C-S-<left>'`C-c C-x       ` '     
            <left>'                
`C-S-<right>'`C-c C-x       ` '     
            <right>'               


File: org,  Node: Interaction,  Next: org-crypt.el,  Prev: TTY keys,  Up: Miscellaneous

15.10 Interaction with other packages
=====================================

Org lives in the world of GNU Emacs and interacts in various ways with
other code out there.

* Menu:

* Cooperation::                 Packages Org cooperates with
* Conflicts::                   Packages that lead to conflicts


File: org,  Node: Cooperation,  Next: Conflicts,  Prev: Interaction,  Up: Interaction

15.10.1 Packages that Org cooperates with
-----------------------------------------

`calc.el' by Dave Gillespie
     Org uses the Calc package for implementing spreadsheet
     functionality in its tables (*note The spreadsheet::).  Org checks
     for the availability of Calc by looking for the function
     `calc-eval' which will have been autoloaded during setup if Calc
     has been installed properly.  As of Emacs 22, Calc is part of the
     Emacs distribution.  Another possibility for interaction between
     the two packages is using Calc for embedded calculations.  *Note
     Embedded Mode: (calc)Embedded Mode.

`constants.el' by Carsten Dominik
     In a table formula (*note The spreadsheet::), it is possible to use
     names for natural constants or units.  Instead of defining your own
     constants in the variable `org-table-formula-constants', install
     the `constants' package which defines a large number of constants
     and units, and lets you use unit prefixes like `M' for `Mega',
     etc.  You will need version 2.0 of this package, available at
     `http://www.astro.uva.nl/~dominik/Tools'.  Org checks for the
     function `constants-get', which has to be autoloaded in your
     setup.  See the installation instructions in the file
     `constants.el'.

`cdlatex.el' by Carsten Dominik
     Org mode can make use of the CDLaTeX package to efficiently enter
     LaTeX fragments into Org files.  See *note CDLaTeX mode::.

`imenu.el' by Ake Stenhoff and Lars Lindberg
     Imenu allows menu access to an index of items in a file.  Org mode
     supports Imenu--all you need to do to get the index is the
     following:
          (add-hook 'org-mode-hook
                    (lambda () (imenu-add-to-menubar "Imenu")))
     By default the index is two levels deep--you can modify the depth
     using the option `org-imenu-depth'.

`remember.el' by John Wiegley
     Org used to use this package for capture, but no longer does.

`speedbar.el' by Eric M. Ludlam
     Speedbar is a package that creates a special frame displaying
     files and index items in files.  Org mode supports Speedbar and
     allows you to drill into Org files directly from the Speedbar.  It
     also allows you to restrict the scope of agenda commands to a file
     or a subtree by using the command `<' in the Speedbar frame.  

`table.el' by Takaaki Ota
     Complex ASCII tables with automatic line wrapping, column- and
     row-spanning, and alignment can be created using the Emacs table
     package by Takaaki Ota (`http://sourceforge.net/projects/table',
     and also part of Emacs 22).  Org mode will recognize these tables
     and export them properly.  Because of interference with other Org
     mode functionality, you unfortunately cannot edit these tables
     directly in the buffer.  Instead, you need to use the command `C-c
     '' to edit them, similar to source code snippets.

    `C-c '     (`org-edit-special')'
          Edit a `table.el' table.  Works when the cursor is in a
          table.el table.  

    `C-c ~     (`org-table-create-with-table.el')'
          Insert a `table.el' table.  If there is already a table at
          point, this command converts it between the `table.el' format
          and the Org mode format.  See the documentation string of the
          command `org-convert-table' for the restrictions under which
          this is possible.
     `table.el' is part of Emacs since Emacs 22.

`footnote.el' by Steven L. Baur
     Org mode recognizes numerical footnotes as provided by this
     package.  However, Org mode also has its own footnote support
     (*note Footnotes::), which makes using `footnote.el' unnecessary.


File: org,  Node: Conflicts,  Prev: Cooperation,  Up: Interaction

15.10.2 Packages that lead to conflicts with Org mode
-----------------------------------------------------

     In Emacs 23, `shift-selection-mode' is on by default, meaning that
     cursor motions combined with the shift key should start or enlarge
     regions.  This conflicts with the use of `S-<cursor>' commands in
     Org to change timestamps, TODO keywords, priorities, and item
     bullet types if the cursor is at such a location.  By default,
     `S-<cursor>' commands outside special contexts don't do anything,
     but you can customize the variable `org-support-shift-select'.
     Org mode then tries to accommodate shift selection by (i) using it
     outside of the special contexts where special commands apply, and
     by (ii) extending an existing active region even if the cursor
     moves across a special context.

`CUA.el' by Kim. F. Storm
     Key bindings in Org conflict with the `S-<cursor>' keys used by
     CUA mode (as well as `pc-select-mode' and `s-region-mode') to
     select and extend the region.  In fact, Emacs 23 has this built-in
     in the form of `shift-selection-mode', see previous paragraph.  If
     you are using Emacs 23, you probably don't want to use another
     package for this purpose.  However, if you prefer to leave these
     keys to a different package while working in Org mode, configure
     the variable `org-replace-disputed-keys'.  When set, Org will move
     the following key bindings in Org files, and in the agenda buffer
     (but not during date selection).

          S-UP      =>  M-p             S-DOWN     =>  M-n
          S-LEFT    =>  M--             S-RIGHT    =>  M-+
          C-S-LEFT  =>  M-S--           C-S-RIGHT  =>  M-S-+

     Yes, these are unfortunately more difficult to remember.  If you
     want to have other replacement keys, look at the variable
     `org-disputed-keys'.

`yasnippet.el'
     The way Org mode binds the TAB key (binding to `[tab]' instead of
     `"\t"') overrules YASnippet's access to this key.  The following
     code fixed this problem:

          (add-hook 'org-mode-hook
                    (lambda ()
                      (org-set-local 'yas/trigger-key [tab])
                      (define-key yas/keymap [tab] 'yas/next-field-or-maybe-expand)))

     The latest version of yasnippet doesn't play well with Org mode.
     If the above code does not fix the conflict, start by defining the
     following function:

          (defun yas/org-very-safe-expand ()
                 (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))

     Then, tell Org mode what to do with the new function:

          (add-hook 'org-mode-hook
                    (lambda ()
                        (make-variable-buffer-local 'yas/trigger-key)
                        (setq yas/trigger-key [tab])
                        (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
                        (define-key yas/keymap [tab] 'yas/next-field)))

`windmove.el' by Hovav Shacham
     This package also uses the `S-<cursor>' keys, so everything written
     in the paragraph above about CUA mode also applies here.  If you
     want make the windmove function active in locations where Org mode
     does not have special functionality on `S-<cursor>', add this to
     your configuration:

          ;; Make windmove work in org-mode:
          (add-hook 'org-shiftup-final-hook 'windmove-up)
          (add-hook 'org-shiftleft-final-hook 'windmove-left)
          (add-hook 'org-shiftdown-final-hook 'windmove-down)
          (add-hook 'org-shiftright-final-hook 'windmove-right)

`viper.el' by Michael Kifer
     Viper uses `C-c /' and therefore makes this key not access the
     corresponding Org mode command `org-sparse-tree'.  You need to find
     another key for this command, or override the key in
     `viper-vi-global-user-map' with

          (define-key viper-vi-global-user-map "C-c /" 'org-sparse-tree)


